Skip to content

Commit 642d8bc

Browse files
committed
doc: @see names a symbol, and @code is code
Two halves of the documentation support, and they turned out to share one reader. **A command that takes a reference names a symbol.** `@see`, `@sa`, `@ref`, `@overload`, `@extends`, `@implements` and `@cite` all take a reference as their first argument (`DocCommandArgs::ReferenceAndBody`), and the server treated it as a *parameter name*: `@see Widget::gr` completed the documented declaration's parameters — the wrong vocabulary — and nothing coloured, hovered or jumped the spelling. It is now one question with the link syntax: * `cpp_parser::doc_references` finds the target on its own line, with a sentence's punctuation trimmed (`@see Foo.` names `Foo`) and a body allowed after it (`@see Foo for the rule`); * `cpp_code_analysis::doc` is the one place that answers "what reference is the cursor on" — a link or a command's argument — and the colour, the hover card, the jump and the completion all ask it there. The hover's own copy of the link scanner is gone; * measured: hovering `@see Widget::grow` answers `void grow(int by)`, `Widget::grow` in `Widget`; `@see Wid` completes `Widget` and nothing else. **An `@code` block is an example of code, not prose.** The prose rule — a comment is not a place a C++ name goes — was applied to the example too, in both directions: * **colour**: a comment produces no tokens, so the tree could not colour the example. `NameKind::Keyword` is new and the block's body is lexed from the text; identifiers resolve through the index as they do anywhere else. Measured: `return` inside `@code` is `Keyword`; * **completion**: `DocCode` answers with the statement list (keywords and snippets), because that is what a reader writing an example is writing. Measured: inside `@code`, `Widget` and `class` are offered. `doc::code_blocks` returns the body **one span per line with the comment marker removed** — the detail that made the first attempt produce nothing: `/// int main() { return 0; }` lexes as a comment, and the marker is a fact about comments rather than about every caller. **A prefix the tree cannot see.** `name_completions_at` reads the position from the tree, and a comment has no node, so it answered with an empty prefix and an empty range — and `names` took that over the caller's `NamePosition`, which meant typing `Wid` after `@see` offered `grow` and `f` beside it. The tree's answer is now treated as a refinement: an empty prefix or range keeps the caller's. Tests: `cpp_parser::doc::a_reference_command_names_the_symbol_after_it`, `cpp_code_analysis`'s `a_reference_command_and_a_code_block_are_classified` and `a_documentation_comment_completes_its_references_and_its_code`. Suites: parser doc 25, analysis semantic 46, completion 58, `cpp_ls` lib 153, the two doc handshake tests, clippy clean.
1 parent 7ef25de commit 642d8bc

14 files changed

Lines changed: 610 additions & 87 deletions

File tree

‎crates/cpp_code_analysis/src/completion/context.rs‎

Lines changed: 49 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -141,6 +141,17 @@ pub enum CompletionContext {
141141
/// The span `written` covers, which is what a client replaces.
142142
range: SourceRange,
143143
},
144+
/// **A word inside an `@code` … `@endcode` block** — an example of code, where a program name belongs.
145+
///
146+
/// The rest of a documentation comment is prose and offers nothing; a code block is the exception, because that
147+
/// is what it is *for*: `@code` exists so a reader can write the call they mean, and a completion that refused
148+
/// while they write it is the same mistake as one that fired in the prose around it, in the other direction.
149+
DocCode {
150+
/// What has been typed of the word at the cursor.
151+
written: String,
152+
/// The span `written` covers, which is what a client replaces.
153+
range: SourceRange,
154+
},
144155
}
145156

146157
/// The context at `offset`, read from the tree.
@@ -296,6 +307,23 @@ pub fn doc_comment_at(root: &CppSyntaxNode, offset: usize) -> Option<CompletionC
296307
return None;
297308
}
298309

310+
// **A code block is an example of *code*** — `@code` … `@endcode` — so its words are the program's, and the
311+
// answer there is the name completion a statement gets rather than the prose refusal below. Asked before every
312+
// other documentation question, because a code block is the innermost scope a cursor in a comment can be in.
313+
if crate::doc::inside_a_code_block(&root.text().to_string(), offset) {
314+
let line_before_cursor = &line[..line.len().min(line.len())];
315+
let typed = line_before_cursor
316+
.trim_end()
317+
.rsplit(|character: char| !(character.is_ascii_alphanumeric() || character == '_'))
318+
.next()
319+
.unwrap_or("");
320+
let start = line_start + line.len().saturating_sub(typed.len());
321+
return Some(CompletionContext::DocCode {
322+
written: typed.to_string(),
323+
range: SourceRange::new(start, typed.len()),
324+
});
325+
}
326+
299327
// **A symbol reference's target**, which is the one position in a comment where a program name belongs.
300328
//
301329
// ```cpp
@@ -356,14 +384,34 @@ pub fn doc_comment_at(root: &CppSyntaxNode, offset: usize) -> Option<CompletionC
356384
text.chars()
357385
.all(|character| character.is_ascii_alphanumeric() || character == '_')
358386
};
387+
388+
// **A command that takes a reference wants a symbol**, not a name the documented declaration declares:
389+
// `@see Widget::gr` is the program's names, which is the same answer a ``[`…`]`` link gets. The argument is
390+
// read as a *target* rather than as a word, because it may be qualified (`Widget::grow`) or templated
391+
// (`vector<int>`) — the things a word test refuses.
392+
if is_a_word(command)
393+
&& cpp_parser::command_args(command) == cpp_parser::DocCommandArgs::ReferenceAndBody
394+
{
395+
let typed = argument.trim();
396+
// A body may follow the reference (`@see Foo for the rule`), and a target never holds a space — so once
397+
// the reader is past one, the position is the body's and there is nothing to complete.
398+
let target = typed.split_whitespace().next().unwrap_or("");
399+
if typed.is_empty() || !typed.contains(char::is_whitespace) {
400+
let start = line_start + line.len().saturating_sub(argument.len());
401+
return Some(CompletionContext::DocLink {
402+
written: target.to_string(),
403+
range: SourceRange::new(start, target.len()),
404+
});
405+
}
406+
}
407+
359408
if is_a_word(command)
360409
&& is_a_word(argument)
361410
&& let Some(kind) = cpp_parser::command_kind(command)
362411
&& matches!(
363412
cpp_parser::command_args(command),
364413
cpp_parser::DocCommandArgs::NameAndBody
365414
| cpp_parser::DocCommandArgs::DirectionalNameAndBody
366-
| cpp_parser::DocCommandArgs::ReferenceAndBody
367415
)
368416
{
369417
// The name starts where the argument starts, which is **the cursor less what has been written** — the

‎crates/cpp_code_analysis/src/completion/mod.rs‎

Lines changed: 28 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -540,6 +540,18 @@ pub fn completion_with(
540540
CompletionContext::DocLink { written, range } => doc_link_names(
541541
index, scopes, root, path, &written, range, cuda, budget, unincluded,
542542
),
543+
// **A code block is code**, so it is answered with the same list a statement gets — keywords and snippets
544+
// included, because that is what a reader writing an example is writing.
545+
CompletionContext::DocCode { written, range } => {
546+
let position = crate::sema::resolve::NamePosition {
547+
scope: String::new(),
548+
written,
549+
range,
550+
};
551+
names(
552+
index, scopes, root, path, &position, 0, true, cuda, budget, unincluded,
553+
)
554+
}
543555
}
544556
}
545557

@@ -1278,8 +1290,22 @@ fn names(
12781290
match listed {
12791291
Known::Yes(listed) => {
12801292
listed_scope = listed.scope.clone();
1281-
listed_prefix = listed.prefix.clone();
1282-
replace = listed.name_range;
1293+
// **The tree's answer is a refinement, and it can say nothing at all.** `name_completions_at` reads the
1294+
// position from the *tree*, and a documentation comment is not in the tree — a `[`Wid`]` target or an
1295+
// `@code` block's word has no node, so the answer comes back with an empty prefix and an empty range. The
1296+
// caller's `NamePosition` is then the only information there is: taking the tree's empty answer over it
1297+
// meant a list of every name in the file beside a replace range of zero characters, so typing `Wid` after
1298+
// `@see ` offered `grow` and `f` too.
1299+
if listed.prefix.is_empty() {
1300+
listed_prefix = position.written.clone();
1301+
} else {
1302+
listed_prefix = listed.prefix.clone();
1303+
}
1304+
replace = if listed.name_range.length == 0 {
1305+
position.range
1306+
} else {
1307+
listed.name_range
1308+
};
12831309
inside_a_scope |= !listed_scope.is_empty();
12841310

12851311
let mut seen: std::collections::HashSet<&str> = std::collections::HashSet::new();
Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
//! **What a documentation comment refers to** — the two spellings a reader writes, read once.
2+
//!
3+
//! A comment refers to the program in two ways, and until this module existed each consumer knew one of them:
4+
//!
5+
//! ```cpp
6+
//! /// See [`Widget::grow`] for the rule. a symbol reference
7+
//! /// @see Widget::grow a command that takes a reference
8+
//! ```
9+
//!
10+
//! Both name a symbol; the first is a *span* found by scanning, the second is a command's first argument. Everything
11+
//! above this layer — the colour, the hover card, the jump, the completion — needs the same answer to the same
12+
//! question, so the question is asked here and every caller shares it. A second copy of the rule would be a second
13+
//! answer to disagree with.
14+
//!
15+
//! The reader itself lives in `cpp_parser` ([`cpp_parser::doc_links`], [`cpp_parser::doc_references`]): finding the
16+
//! spans is a question about a comment's text, and that is the parser's business. This module decides *which* of the
17+
//! two a cursor is in, and where a documentation comment begins and ends.
18+
19+
use cpp_parser::SourceRange;
20+
21+
/// A symbol a documentation comment names: the span it is written in, and the spelling as written.
22+
#[derive(Debug, Clone, PartialEq, Eq)]
23+
pub struct DocTarget {
24+
/// The span of the *target* — the text between a link's backticks, or the argument of `@see` — in the file.
25+
pub range: SourceRange,
26+
/// The spelling, as written: `Widget::grow`, `std::vector<int>`, `widget.h`.
27+
pub target: String,
28+
}
29+
30+
impl DocTarget {
31+
/// The spelling with the punctuation a *reference* may add, removed: `grow()` and `MAX!` name `grow` and `MAX`.
32+
///
33+
/// Rust's links write `()` to say "this is a call" and `!` to say "this is a macro", and a reader writing C++
34+
/// prose does the same. Neither is part of the name, and a lookup that kept them would resolve nothing.
35+
pub fn spelled_for_a_lookup(&self) -> &str {
36+
self.target
37+
.trim_end_matches("()")
38+
.trim_end_matches('!')
39+
.trim()
40+
}
41+
}
42+
43+
/// The reference the cursor at `offset` is on, if it is on one.
44+
///
45+
/// A link is asked first: it is the narrower span, and a link written *inside* a command's argument would otherwise be
46+
/// answered by the wider one.
47+
pub fn target_at(text: &str, offset: usize) -> Option<DocTarget> {
48+
let whole = SourceRange::new(0, text.len());
49+
let holds = |range: &SourceRange| range.start_offset <= offset && offset <= range.end_offset();
50+
51+
if let Some(link) = cpp_parser::doc_links(text, whole)
52+
.into_iter()
53+
.find(|link| holds(&link.range))
54+
{
55+
return Some(DocTarget {
56+
range: link.range,
57+
target: link.target,
58+
});
59+
}
60+
61+
cpp_parser::doc_references(text, whole)
62+
.into_iter()
63+
.find(|reference| holds(&reference.range))
64+
.map(|reference| DocTarget {
65+
range: reference.range,
66+
target: reference.target,
67+
})
68+
}
69+
70+
/// Every reference in the text, links and command arguments together, in the order they are written.
71+
pub fn targets(text: &str) -> Vec<DocTarget> {
72+
let whole = SourceRange::new(0, text.len());
73+
let mut found: Vec<DocTarget> = cpp_parser::doc_links(text, whole)
74+
.into_iter()
75+
.map(|link| DocTarget {
76+
range: link.range,
77+
target: link.target,
78+
})
79+
.chain(
80+
cpp_parser::doc_references(text, whole)
81+
.into_iter()
82+
.map(|reference| DocTarget {
83+
range: reference.range,
84+
target: reference.target,
85+
}),
86+
)
87+
.collect();
88+
found.sort_by_key(|target| (target.range.start_offset, target.range.end_offset()));
89+
found
90+
}
91+
92+
/// **Is this offset inside a documentation comment?** — the gate both a reference and a completion have to pass.
93+
///
94+
/// A documentation comment is `///` or `//!` on its own line, and `/**`-`/*!` … `*/` for a block; a `//` or `/*` is a
95+
/// comment and not documentation, which is Doxygen's own rule. Asked of the *text* rather than of the lexer's tokens,
96+
/// because a backtick is not a C++ token: `/// See [`Wid` lexes as a comment followed by an unrecognised character
97+
/// and an identifier, and a token-based test answered "code" for the middle of a comment.
98+
pub fn is_a_documentation_comment(text: &str, offset: usize) -> bool {
99+
let offset = offset.min(text.len());
100+
let before = &text[..offset];
101+
let line_start = before.rfind('\n').map_or(0, |at| at + 1);
102+
let trimmed = text[line_start..].trim_start();
103+
104+
if trimmed.starts_with("///") || trimmed.starts_with("//!") || trimmed.starts_with("/**") {
105+
return true;
106+
}
107+
108+
// A `/** … */` block's *middle* lines do not begin with the marker, so the block itself is the question: the
109+
// nearest opener is the one that matters, and it counts only if nothing closed it first.
110+
match (before.rfind("/*"), before.rfind("*/")) {
111+
(Some(opened), closed) => {
112+
let still_open = closed.is_none_or(|closed| closed < opened);
113+
still_open
114+
&& (before[opened..].starts_with("/**") || before[opened..].starts_with("/*!"))
115+
}
116+
_ => false,
117+
}
118+
}
119+
120+
/// **Every `@code` … `@endcode` body in `text`**, as spans of the file — **one span per line, comment marker removed**.
121+
///
122+
/// The block's *interior* only: the delimiters are commands and are drawn as such, while the body is an example of
123+
/// code — which is what a highlighter and a completion treat differently from prose.
124+
///
125+
/// # Why the marker is stripped here rather than by every caller
126+
///
127+
/// A code block is written *inside* a comment, so each of its lines begins with the comment's own marker —
128+
/// `/// int main() { return 0; }`, or ` *` in a `/** */` block. A caller that lexed the raw line would see a comment
129+
/// and produce no tokens at all, which is exactly what the first version of the highlighter did. Removing the marker
130+
/// is a fact about comments, which is this module's business, and what comes back is the code, in file coordinates.
131+
pub fn code_blocks(text: &str) -> Vec<SourceRange> {
132+
let mut spans = Vec::new();
133+
let mut at = 0usize;
134+
135+
while let Some(open) = text[at..]
136+
.find("@code")
137+
.map(|offset| at + offset)
138+
.or_else(|| text[at..].find("\\code").map(|offset| at + offset))
139+
{
140+
let opens_at = open + "@code".len();
141+
// The body starts after the rest of the `@code` line — `@code{.cpp}` is a spelling too, and either way what
142+
// is written after the command on its own line is still the command's argument rather than the example.
143+
let start = text[opens_at..]
144+
.find('\n')
145+
.map_or(text.len(), |offset| opens_at + offset + 1);
146+
let close = text[start..]
147+
.find("@endcode")
148+
.map(|offset| start + offset)
149+
.or_else(|| text[start..].find("\\endcode").map(|offset| start + offset));
150+
let end = close.unwrap_or(text.len());
151+
152+
let mut line_start = start;
153+
for line in text[start..end].split_inclusive('\n') {
154+
let indentation = line.len() - line.trim_start().len();
155+
let body = line.trim_start();
156+
let marker = if let Some(rest) = body
157+
.strip_prefix("///")
158+
.or_else(|| body.strip_prefix("//!"))
159+
.or_else(|| body.strip_prefix("//"))
160+
.or_else(|| body.strip_prefix('*'))
161+
{
162+
body.len() - rest.len()
163+
} else {
164+
0
165+
};
166+
let content = body[marker..].trim_end_matches(['\r', '\n']);
167+
let content = content.strip_prefix(' ').unwrap_or(content);
168+
if !content.trim().is_empty() {
169+
spans.push(SourceRange::new(
170+
line_start + indentation + marker,
171+
content.len(),
172+
));
173+
}
174+
line_start += line.len();
175+
}
176+
177+
match close {
178+
Some(end) => at = end + "@endcode".len(),
179+
None => break,
180+
}
181+
}
182+
183+
spans
184+
}
185+
186+
/// **Is the offset inside an `@code` … `@endcode` block?** — where a comment is an example of code rather than prose.
187+
///
188+
/// The commands nest by *line*, which is how Doxygen writes them: `@code` opens on one `///` line and `@endcode`
189+
/// closes several lines later, and each of those lines is a separate comment as far as the C++ lexer is concerned.
190+
/// So the question is which of the two came last before the cursor, not whether the cursor's own line is a comment.
191+
pub fn inside_a_code_block(text: &str, offset: usize) -> bool {
192+
let offset = offset.min(text.len());
193+
let before = &text[..offset];
194+
let opened = before.rfind("@code").or_else(|| before.rfind("\\code"));
195+
let closed = before
196+
.rfind("@endcode")
197+
.or_else(|| before.rfind("\\endcode"));
198+
199+
match (opened, closed) {
200+
(Some(opened), Some(closed)) => opened > closed,
201+
(Some(_), None) => true,
202+
_ => false,
203+
}
204+
}

‎crates/cpp_code_analysis/src/lib.rs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,7 @@ pub mod align;
6767
pub mod cache;
6868
pub mod completion;
6969
pub mod cuda;
70+
pub mod doc;
7071
pub mod effect;
7172
pub mod file;
7273
pub mod folding;

‎crates/cpp_code_analysis/src/semantic.rs‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,12 @@ pub enum NameKind {
126126
Parameter,
127127
/// A name this file `#define`s.
128128
Macro,
129+
/// **A keyword written inside an `@code` block of a documentation comment** — where an example is code.
130+
///
131+
/// The one name this layer reports for *text in a comment*. A code block is an example of the language, and a
132+
/// reader expects `for` and `return` inside it to look like `for` and `return` — the tree has no tokens there
133+
/// (a comment is trivia), so the only layer that can say so is this one, which has the file's text.
134+
Keyword,
129135
}
130136

131137
/// Where a classification came from — which layer answered, and therefore how strong the answer is.

0 commit comments

Comments
 (0)