|
| 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 | +} |
0 commit comments