Skip to main content

Module doc

Module doc 

Source
Expand description

What a documentation comment refers to — the names a hover draws as links. What a documentation comment refers to — the two spellings a reader writes, read once.

A comment refers to the program in two ways, and until this module existed each consumer knew one of them:

/// See [`Widget::grow`] for the rule.        a symbol reference
/// @see Widget::grow                          a command that takes a reference

Both name a symbol; the first is a span found by scanning, the second is a command’s first argument. Everything above this layer — the colour, the hover card, the jump, the completion — needs the same answer to the same question, so the question is asked here and every caller shares it. A second copy of the rule would be a second answer to disagree with.

The reader itself lives in cpp_parser (cpp_parser::doc_links, cpp_parser::doc_references): finding the spans is a question about a comment’s text, and that is the parser’s business. This module decides which of the two a cursor is in, and where a documentation comment begins and ends.

Structs§

DocTarget
A symbol a documentation comment names: the span it is written in, and the spelling as written.

Functions§

code_blocks
Every @code … @endcode body in text, as spans of the file — one span per line, comment marker removed.
inside_a_code_block
Is the offset inside an @code … @endcode block? — where a comment is an example of code rather than prose.
is_a_documentation_comment
Is this offset inside a documentation comment? — the gate both a reference and a completion have to pass.
target_at
The reference the cursor at offset is on, if it is on one.
targets
Every reference in the text, links and command arguments together, in the order they are written.