Skip to content

Commit bc113ff

Browse files
committed
readme: @see is a symbol reference, and @code is code
The documentation section now says what the server does with the two shapes it gained: a command that takes a reference (`@see`, `@sa`, `@ref`, `@overload`, `@extends`, `@implements`, `@cite`) completes the program's names rather than the documented declaration's parameters, and an `@code` block is coloured and completed as code — with the marker-stripping detail that makes it work. The reference table's *definition* row now says a macro's reference jumps to its `#define`, and the decisions list gains the one this work made: a reference's body is prose, because a target never holds a space.
1 parent 642d8bc commit bc113ff

1 file changed

Lines changed: 18 additions & 6 deletions

File tree

‎README.md‎

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -100,33 +100,45 @@ from the buffer the reader is editing.
100100
the table are vocabulary the server knows:
101101

102102
- **hover** on a command explains it, and a declaration's own comment is rendered in its card;
103-
- **completion** offers the command names (`/// @par` → `param`, `tparam`, `par`, `paragraph`) and, after a command
104-
that takes one, the names of the declaration being documented (`@param |` → its parameters);
103+
- **completion** offers the command names (`/// @par` → `param`, `tparam`, `par`, `paragraph`); after a command that
104+
takes a name, the parameters of the declaration being documented (`@param |` → its parameters); and after one that
105+
takes a **reference** — `@see`, `@sa`, `@ref`, `@overload`, `@extends`, `@implements`, `@cite` — the program's
106+
names, exactly as a `` [`…`] `` link gets them;
105107
- **semantic tokens** draw a command as `decorator`, which a client can remap on its own — the cppls extension draws
106108
`keyword.doxygen` from it;
107109
- a command's *body* is the reader's, and the server does not colour it.
108110

109-
**Symbol references.** Rust's intra-doc link, in a C++ comment:
111+
**Code blocks.** `@code` … `@endcode` is an example of code, not prose, and it is treated as one: the block's
112+
keywords and resolvable names are coloured like the code around it, and completion inside the block offers what a
113+
statement offers — keywords and snippets included. The body is read **per line with the comment marker removed**, so
114+
`/// int main() { return 0; }` lexes as code rather than as another comment.
115+
116+
**Symbol references.** Rust's intra-doc link, in a C++ comment — and Doxygen's own spelling of the same thing:
110117

111118
```cpp
112119
/// See [`Widget::grow`] for the rule, [`std::vector`] for the container, and [`grow()`] for the call.
120+
/// @see Widget::grow
113121
struct Widget { void grow(int by); };
114122
```
115123
116124
| Position | What happens |
117125
| --- | --- |
118126
| The target | Coloured as the declaration it names — a function, a type, a macro — and **not** coloured when nothing declares it: a colour would say the name is known |
119127
| hover | The declaration's card, the same one a name gets |
120-
| definition | Jumps to the declaration; a macro's link jumps to its `#define`, which is the only place a reader can go for one |
121-
| completion | The names this file can see — and only names, never a snippet: a link takes a symbol |
128+
| definition | Jumps to the declaration; a macro's reference jumps to its `#define`, which is the only place a reader can go for one |
129+
| completion | The names this file can see — and only names, never a snippet: a reference takes a symbol |
130+
131+
Both spellings are one question, answered in one place (`cpp_code_analysis::doc`), which is why the colour, the card
132+
and the jump cannot disagree about what a reference names.
122133
123-
Three details worth stating, because they are decisions rather than accidents:
134+
Four details worth stating, because they are decisions rather than accidents:
124135
125136
* **Only the backticked form.** `[target]` without the backticks is what Rust also accepts, and in a C++ comment it
126137
collides with the most ordinary prose there is: `arr[i]` and `matrix[row][col]`. The backtick is the whole
127138
disambiguator, and a target with whitespace in it is a title rather than a link.
128139
* **`()` and `!` are punctuation, not part of the name.** `` [`grow()`] `` says "this is a call" and `` [`MAX_SIZE!`] ``
129140
says "this is a macro"; both are trimmed before the lookup, and the range still covers what was written.
141+
* **A reference's body is prose.** `@see Foo for the rule` names `Foo`: a target never holds a space.
130142
* **Prose offers nothing.** A cursor anywhere else in a documentation comment completes nothing at all — a comment is
131143
not a place a C++ name goes — while ordinary identifiers still get the client's own colour.
132144

0 commit comments

Comments
 (0)