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 referenceBoth 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…@endcodebody intext, as spans of the file — one span per line, comment marker removed. - inside_
a_ code_ block - Is the offset inside an
@code…@endcodeblock? — 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
offsetis on, if it is on one. - targets
- Every reference in the text, links and command arguments together, in the order they are written.