Associates line comments with the declarations they document.
The lexer drops comments from the token stream and preserves their byte spans on ParseOutcome.comments; every Decl carries its own byte span. This pass joins the two sorted lists without touching the parser: a contiguous run of comment lines attaches to the declaration whose first token begins on the line directly below the run. The scan from a comment run to its decl moves FORWARD over whitespace and the leading modifier keywords (pub, static, mut, consuming), which the parser consumes before the decl's own span starts. A blank line anywhere in the gap detaches the run, and a comment sharing its line with preceding code is trailing — both land in orphans.
Only decls reachable from file items and nominal bodies are considered (variants, properties, methods, inits, requirements, nested nominals); local decls inside function bodies are skipped. Entries carry the decl's span as the join key back to the AST, in source order, so consumers can merge-join while walking the tree.
parse_file_source leaves ParseOutcome.docs empty; the parse_file_docs_source entry point runs this pass so consumers that do not need documentation never pay for it.
API Reference
Structs
struct DocIndex
The result of joining scanner comment spans to parser declaration spans.
Functions
func collect_doc_comments(source: String, outcome: &ParseOutcome) -> DocIndex
Attaches leading line-comment groups without changing the parser token stream.
func parse_file_docs_source(source: String) -> ParseOutcome
The documenting whole-file entry: the plain parse plus this pass's attachments on ParseOutcome.docs. parse_file_source leaves docs empty so consumers that never read documentation do not pay for it.