big_code_analysis_ast/lang_helpers/doc_comment.rs
1//! Doc-comment binding: which comments document, by where they sit and
2//! by the declaration after them (#1597, #1613). The per-tool marker
3//! tests these rules consult live in [`super::doc_text`] and are
4//! re-exported here, so a `Checker` or role row names one path for both
5//! halves (#1649).
6
7pub(crate) use super::doc_text::{
8 csharp_doc, doxygen, go_directive, java_doc, javadoc_block, jsdoc_virtual, kotlin_doc,
9 ldoc_opener, lua_long_comment, phpdoc, pod_comment_region, ruby_directive_opener,
10 ruby_magic_comment, tsdoc_block, tsdoc_module,
11};
12use crate::checker::Checker;
13use crate::node::{Ancestors, FoldLane, Node};
14
15/// How a language's tool attaches a doc comment to the declaration after
16/// it (#1613), read from each tool's source rather than its manual
17/// (lesson 98); see [`Checker::DOC_BINDING`]. A forward doc comment that
18/// the binding does not attach documents nothing and is billed as a plain
19/// comment.
20///
21/// The doc comments compared are those of one *stretch*: the comment
22/// siblings between two other siblings, read past the ones
23/// [`skips`](Self::skips) names. Blank rows never split a stretch; none of
24/// the bound tools reads them.
25#[derive(Clone, Copy, Debug)]
26pub struct DocBinding {
27 /// Which doc comments of a stretch the tool attaches.
28 pub kept: KeptDocs,
29 /// A sibling that may sit between a doc comment and its target
30 /// without detaching it, so a stretch reads past it: rustc gives an
31 /// item every outer doc comment above it, through its other
32 /// attributes. A grammar that nests annotations inside the declaration
33 /// has nothing to skip. A skipped node is never a target. The
34 /// [`Ancestors`] are the node's chain.
35 pub skips: for<'a, 'b> fn(&Node<'a>, Ancestors<'a, 'b>) -> bool,
36 /// Whether a doc comment documents what follows it. `false` leaves it
37 /// to where it sits, as in an unbound language: Rust's inner `//!`
38 /// documents the item enclosing it, a doc comment in a macro token
39 /// tree documents whatever the expansion makes of it, and a KDoc
40 /// inside a Kotlin declaration's signature is read by `findDocComment`
41 /// from there. The [`Ancestors`] are the comment's chain.
42 pub forward: for<'a, 'b> fn(&Node<'a>, &[u8], Ancestors<'a, 'b>) -> bool,
43 /// A doc comment that documents an entry of its own and takes with it
44 /// the forward doc comments before it in its stretch, so they document
45 /// even when the stretch ends at no target: Doxygen gives a `\file`
46 /// block the doc blocks it has gathered since the last entry, so a
47 /// licence block above one at the end of a header documents the file.
48 /// It should not itself bind [`forward`](Self::forward). Where the
49 /// stretch does end at a target, [`kept`](Self::kept) alone decides.
50 /// `None` for a tool with no such block, which lets a stretch that
51 /// ends at no target return before it is even collected.
52 pub gathers: Option<fn(&Node, &[u8]) -> bool>,
53}
54
55impl DocBinding {
56 /// A binding that keeps `kept`, skips no sibling, binds every doc
57 /// comment forward, and has no doc comment gather the others.
58 #[must_use]
59 pub const fn new(kept: KeptDocs) -> Self {
60 Self {
61 kept,
62 skips: |_, _| false,
63 forward: |_, _, _| true,
64 gathers: None,
65 }
66 }
67}
68
69/// Which doc comments of a stretch a [`DocBinding`] attaches.
70#[derive(Clone, Copy, Debug)]
71pub enum KeptDocs {
72 /// Every doc comment of the stretch: rustc gives an item all the outer
73 /// doc comments above it, across blank rows, plain comments and other
74 /// attributes, which rustdoc concatenates.
75 All,
76 /// The last doc comment before the declaration's first token, and the
77 /// doc comments before it that `joins(earlier, later, code)` makes one
78 /// comment with it: javac's `Token::docComment` and Kotlin's
79 /// `PrecedingDocCommentsBinder` keep the last, and javac's
80 /// dangling-doc-comments lint names the rest. A skipped node is that
81 /// first token, a Kotlin annotation the grammar leaves outside its
82 /// declaration; when no doc comment precedes it, the first one after
83 /// it is read, as `findDocComment` reads Kotlin's modifier list.
84 Last {
85 /// Whether two adjacent doc comments are one to the tool.
86 joins: fn(&Node, &Node, &[u8]) -> bool,
87 },
88 /// The stretch's last comment, if it is a doc comment: Groovy's
89 /// `GroovydocManager` reads the comment nearest the declaration and
90 /// drops it unless it opens `/**`, so a plain comment in between
91 /// detaches it. A comment for which `hidden(comment, next)` holds,
92 /// `next` being the sibling after it, is invisible to the tool and
93 /// read past.
94 Nearest {
95 /// Whether the tool cannot see a comment.
96 hidden: fn(&Node, &Node) -> bool,
97 },
98 /// What a reverse scan over the declaration's leading trivia keeps,
99 /// from its first token back: past the comments and skipped nodes
100 /// `hidden(node, code)` names to the nearest other comment, kept if it
101 /// is a doc comment, then on over the doc comments directly before it
102 /// that `joins(earlier, later, code)` makes one with it. A member
103 /// directly before them that is hidden or plain ends the run. A skipped
104 /// node `hidden` does not name is the first token — a decorator the
105 /// grammar leaves outside its declaration — so a doc comment after it
106 /// documents nothing. Roslyn's `GetDocumentationCommentTriviaFromSyntaxNode`
107 /// reads past plain comments and directives and keeps adjacent doc
108 /// comments; JSDoc's `getLeadingJsdocComment` reads past line comments
109 /// only; tsc reads past every plain comment.
110 Leading {
111 /// Whether the scan reads past a member to the one before it.
112 hidden: fn(&Node, &[u8]) -> bool,
113 /// Whether two adjacent doc comments are one to the tool.
114 joins: fn(&Node, &Node, &[u8]) -> bool,
115 /// Whether the tool reads a member on the row where the code
116 /// before the stretch ends, asked of the target. tsc's
117 /// `getLeadingCommentRanges` starts at the line break after the
118 /// token before the declaration, so `x; /** d */` documents
119 /// nothing after it, except before a parameter, whose trailing
120 /// comment ranges it reads too; Roslyn and JSDoc read it.
121 after_code: fn(&Node) -> bool,
122 },
123}
124
125/// A [`KeptDocs::Last`] join that joins nothing.
126#[must_use]
127pub(crate) fn never_joins(_: &Node, _: &Node, _: &[u8]) -> bool {
128 false
129}
130
131/// The bytes of `node`'s own span, or nothing when the span is outside
132/// `code` — a recovery token can point past the source. Used for comment
133/// markers and for the identifiers the positional rules read.
134#[inline]
135#[must_use]
136pub(crate) fn node_bytes<'a>(node: &Node, code: &'a [u8]) -> &'a [u8] {
137 code.get(node.start_byte()..node.end_byte()).unwrap_or(&[])
138}
139
140/// The spelling of `node` as its tokens: the bytes of every leaf of its
141/// subtree that `C::is_comment` does not name, with ASCII whitespace
142/// removed — what a layout- and comment-insensitive comparison reads, so
143/// `Map<String, T>`, `Map<String,T>` and `Map</* k */ String, T>` are one
144/// spelling (#1842). A comment subtree is skipped whole, so a grammar
145/// whose comment holds children contributes none of them. One stack and
146/// one cursor, as [`Node::preorder`] walks.
147#[must_use]
148pub(crate) fn token_spelling<C: Checker>(node: &Node, code: &[u8]) -> Vec<u8> {
149 let mut spelling = Vec::new();
150 let mut stack = vec![*node];
151 let mut cursor = node.cursor();
152 while let Some(current) = stack.pop() {
153 if C::is_comment(¤t) {
154 continue;
155 }
156 if current.child_count() == 0 {
157 spelling.extend(
158 node_bytes(¤t, code)
159 .iter()
160 .filter(|b| !b.is_ascii_whitespace()),
161 );
162 continue;
163 }
164 let first_child = stack.len();
165 stack.extend(current.children_with(&mut cursor));
166 stack[first_child..].reverse();
167 }
168 spelling
169}
170
171/// Whether `comment` lies outside every function and closure body, by the
172/// same fold [`documents_where_it_sits`] runs, for a language whose
173/// in-body doc comments document wherever they sit and so must not bind.
174#[must_use]
175pub(crate) fn outside_function_bodies<'a, T: Checker>(
176 comment: &Node<'a>,
177 code: &[u8],
178 ancestors: Ancestors<'a, '_>,
179) -> bool {
180 !held_in_body::<T>(comment, code, 0, ancestors)
181}
182
183/// Whether an ancestor of `node`, past the `skip` nearest ones, holds it
184/// in a function body. One step closure for the shared
185/// [`FoldLane::DocInBody`] memo: `fold_down` serves a cached answer to
186/// every caller on the lane, so the question must be asked the same way
187/// everywhere.
188fn held_in_body<'a, T: Checker>(
189 node: &Node<'a>,
190 code: &[u8],
191 skip: usize,
192 ancestors: Ancestors<'a, '_>,
193) -> bool {
194 ancestors.fold_down(
195 node,
196 skip,
197 FoldLane::DocInBody,
198 0,
199 |held, ancestor, outer, below| {
200 u8::from(held != 0 || T::holds_doc_comment_in_body(ancestor, code, outer, below))
201 },
202 ) != 0
203}
204
205// ---------------------------------------------------------------------
206// Documentation by position: Go, Ruby and Lua have no doc marker the
207// grammar or a tool reads per comment. go/doc's lead comment is "a
208// comment group that starts and ends in a line without any other
209// tokens and that is followed by a non-comment token on the line
210// immediately after" (go/parser); YARD attaches the comment lines
211// directly above a `def`, `class` or `module`; LDoc opens a block on
212// `---` and continues it over the `--` rows that follow until a blank
213// line. All three are properties of a *run* of comment siblings, not of
214// one node, so they are decided once per run, at its last member.
215// ---------------------------------------------------------------------
216
217/// The place half of the documentation test, for a comment already
218/// spelled or placed as documentation: it documents unless an ancestor
219/// holds it in a function or closure body
220/// ([`Checker::holds_doc_comment_in_body`]) without the comment opening
221/// that body as its documentation ([`Checker::doc_comment_opens_body`],
222/// asked of the two nearest ancestors only) and the language's tool
223/// ignores in-body doc comments
224/// ([`Checker::DOC_COMMENTS_IN_FUNCTION_BODIES`]). Shared by the marker
225/// languages' comment arms and by Lua's LDoc opener (#1597).
226#[must_use]
227pub fn documents_where_it_sits<'a, T: Checker>(
228 node: &Node<'a>,
229 code: &[u8],
230 ancestors: Ancestors<'a, '_>,
231) -> bool {
232 if T::DOC_COMMENTS_IN_FUNCTION_BODIES {
233 return true;
234 }
235 // The two nearest ancestors may excuse the comment itself
236 // (`Checker::doc_comment_opens_body`: Rust's inner doc heading a
237 // body); every ancestor above them answers by the path alone, folded
238 // once per walk rather than climbed once per comment.
239 let mut below = *node;
240 for (ancestor, outer) in ancestors.iter(node).take(2) {
241 if T::holds_doc_comment_in_body(&ancestor, code, outer, &below)
242 && !T::doc_comment_opens_body(node, &ancestor, &below, code)
243 {
244 return false;
245 }
246 below = ancestor;
247 }
248 !held_in_body::<T>(node, code, 2, ancestors)
249}
250
251/// Whether a doc comment documents without a following declaration,
252/// before [`documents_where_it_sits`] has its say: every doc comment of a
253/// language with no [`Checker::DOC_BINDING`], and a bound language's that
254/// does not attach forward ([`DocBinding::forward`]). A forward one
255/// documents only through [`bound_doc_run`] (#1613).
256#[must_use]
257pub fn documents_unbound<'a, T: Checker>(
258 comment: &Node<'a>,
259 code: &[u8],
260 ancestors: Ancestors<'a, '_>,
261) -> bool {
262 T::DOC_BINDING.is_none_or(|binding| !(binding.forward)(comment, code, ancestors))
263}
264
265/// Credits the doc comments a bound language's tool attaches to the
266/// declaration after them (#1613). Called from the LOC comment arm for
267/// every comment; `credit` receives each attached doc comment, whose own
268/// arm has already billed its rows as `cloc`. A language with no
269/// [`Checker::DOC_BINDING`] credits nothing here.
270///
271/// The comments compared are one *stretch*: the comment siblings between
272/// two other siblings, read past those [`DocBinding::skips`] names and any
273/// parse error that is no doc target and holds none. Only the stretch's last
274/// comment does more than one sibling step, so a stretch of `k` members
275/// costs `O(k)` steps in total, the #1446 bound: it finds the sibling the
276/// stretch ends at and, when that is an [`Checker::is_doc_target`], walks
277/// back once to credit what the binding keeps. A stretch that ends
278/// anywhere else — a statement, a macro call, a closing brace, the end of
279/// the file — documents nothing. Members are siblings, so one in-body test
280/// ([`documents_where_it_sits`]) answers for them all.
281pub fn bound_doc_run<'a, T: Checker>(
282 comment: &Node<'a>,
283 code: &[u8],
284 ancestors: Ancestors<'a, '_>,
285 mut credit: impl FnMut(&Node<'a>),
286) {
287 let Some(binding) = T::DOC_BINDING else {
288 return;
289 };
290 let end = match stretch_end::<T>(comment, code, ancestors, binding.skips) {
291 // A later member decides.
292 StretchEnd::Undecided => return,
293 // Nothing documents, and no block gathers the stretch either.
294 StretchEnd::Elsewhere if binding.gathers.is_none() => return,
295 end => end,
296 };
297 if !documents_where_it_sits::<T>(comment, code, ancestors) {
298 return;
299 }
300 let (stretch, code_before) = collect_stretch::<T>(comment, code, ancestors, binding.skips);
301 let forward =
302 |n: &Node<'a>| T::is_doc_comment(n, code) && (binding.forward)(n, code, ancestors);
303 let StretchEnd::AtTarget { next, target } = end else {
304 if let Some(gathers) = binding.gathers {
305 bind_gathered::<T>(&stretch, code, gathers, forward)
306 .iter()
307 .for_each(&mut credit);
308 }
309 return;
310 };
311 let kept = match binding.kept {
312 KeptDocs::All => stretch.iter().copied().filter(forward).collect(),
313 KeptDocs::Last { joins } => bind_last::<T>(&stretch, code, joins, forward),
314 KeptDocs::Nearest { hidden } => bind_nearest::<T>(&stretch, next, hidden, forward)
315 .into_iter()
316 .collect(),
317 KeptDocs::Leading {
318 hidden,
319 joins,
320 after_code,
321 } => {
322 // A member on the row the code before the stretch ends on is
323 // after that code, where a scan from the next line break does
324 // not reach.
325 let after_code_row = code_before
326 .filter(|_| !after_code(&target))
327 .map(|before| before.end_row());
328 let attaches = |n: &Node<'a>| forward(n) && Some(n.start_row()) != after_code_row;
329 bind_leading::<T>(&stretch, code, hidden, joins, attaches)
330 }
331 };
332 kept.iter().for_each(&mut credit);
333}
334
335/// Where a stretch of comments ends, asked of its last comment.
336enum StretchEnd<'a> {
337 /// A later comment of the stretch decides.
338 Undecided,
339 /// At `target`, an [`Checker::is_doc_target`] or a parse error holding
340 /// one. `next` is the sibling right after the asking comment, where a
341 /// walk back from the target begins.
342 AtTarget { next: Node<'a>, target: Node<'a> },
343 /// At a statement, a closing brace, the end of the file — anything
344 /// that documents nothing.
345 Elsewhere,
346}
347
348/// Where the stretch `comment` belongs to ends. The scan stops at the
349/// first sibling that is neither skipped nor a parse error read past, so
350/// it never passes a later comment of the stretch. Only an error is asked
351/// whether it is read past, and only once the binding's own `skips` and
352/// [`Checker::is_doc_target`] have passed on it, so a binding that decides
353/// errors itself (Doxygen's) keeps its reading.
354fn stretch_end<'a, T: Checker>(
355 comment: &Node<'a>,
356 code: &[u8],
357 ancestors: Ancestors<'a, '_>,
358 skips: for<'b> fn(&Node<'a>, Ancestors<'a, 'b>) -> bool,
359) -> StretchEnd<'a> {
360 let mut after = ancestors.siblings_after(comment).peekable();
361 let Some(&next) = after.peek() else {
362 return StretchEnd::Elsewhere;
363 };
364 match after.find(|n| !skips(n, ancestors) && !read_past_error::<T>(n, code, ancestors)) {
365 Some(target) if T::is_comment(&target) => StretchEnd::Undecided,
366 Some(target)
367 if T::is_doc_target(&target, code, ancestors)
368 || (target.is_error() && error_holds_target::<T>(&target, code, ancestors)) =>
369 {
370 StretchEnd::AtTarget { next, target }
371 }
372 _ => StretchEnd::Elsewhere,
373 }
374}
375
376/// The stretch `comment` ends, in source order, and the sibling before it:
377/// `comment` and the siblings before it that are comments or skipped,
378/// read past the parse errors [`stretch_end`] reads past with the same
379/// test, so every member whose scan stopped at the next comment is in
380/// the stretch that decides it. The errors themselves are left out: the
381/// `safe` of a `safe fn` is between the item's doc comments and its
382/// first token, not that token. An error the scan does not read past —
383/// one holding a target — ends the stretch and is the sibling before it.
384fn collect_stretch<'a, T: Checker>(
385 comment: &Node<'a>,
386 code: &[u8],
387 ancestors: Ancestors<'a, '_>,
388 skips: for<'b> fn(&Node<'a>, Ancestors<'a, 'b>) -> bool,
389) -> (Vec<Node<'a>>, Option<Node<'a>>) {
390 let mut stretch = vec![*comment];
391 let mut before = None;
392 // An error read past is no member of the stretch: neither a comment
393 // nor the first token a binder stops at. Left in, a binder that keeps
394 // the last doc comment before the first token (tsc's, JSDoc's,
395 // javac's) would read the error as that token and keep the comment
396 // above it instead of the one the tool attaches.
397 for sibling in ancestors
398 .siblings_before(comment)
399 .filter(|sibling| !read_past_error::<T>(sibling, code, ancestors))
400 {
401 if T::is_comment(&sibling) || skips(&sibling, ancestors) {
402 stretch.push(sibling);
403 } else {
404 before = Some(sibling);
405 break;
406 }
407 }
408 stretch.reverse();
409 (stretch, before)
410}
411
412/// Whether a stretch reads past `node`: a parse error that is no doc
413/// target and holds none — tokens the grammar could not place, such as the
414/// `safe` of a Rust 2024 foreign item, which tree-sitter-rust leaves as an
415/// error between the item's doc comment and the rest of it. Given the
416/// benefit of the doubt, as Doxygen's binding gives one (`doxygen_skips`),
417/// rather than dropping the doc comment on a parse failure.
418fn read_past_error<'a, T: Checker>(
419 node: &Node<'a>,
420 code: &[u8],
421 ancestors: Ancestors<'a, '_>,
422) -> bool {
423 node.is_error()
424 && !T::is_doc_target(node, code, ancestors)
425 && !error_holds_target::<T>(node, code, ancestors)
426}
427
428/// Whether a child of the parse error `error` is a doc target: a
429/// declaration parsed amid code the grammar could not place, which the
430/// error then stands in for as Doxygen's `doxygen_target` reads one.
431/// `ancestors` is the error's chain, and its children are judged with
432/// [`Ancestors::of_children`] of it, which borrows the walk's chain and
433/// carries the walk's memo, so Doxygen's conditionals under the error
434/// are read once per walk like any other (#1686 review). Without a
435/// chain the children are judged with none, which a target test that
436/// climbs pays for at `O(depth)`; every production walk lends one, so
437/// only a test reaches that fallback.
438fn error_holds_target<'a, T: Checker>(
439 error: &Node<'a>,
440 code: &[u8],
441 ancestors: Ancestors<'a, '_>,
442) -> bool {
443 let under = ancestors.of_children(error);
444 let inside = under.get();
445 error
446 .children()
447 .any(|child| child.is_named() && T::is_doc_target(&child, code, inside))
448}
449
450/// What a stretch that ends at no target documents: what its last
451/// gathering comment ([`DocBinding::gathers`]) takes — the forward doc
452/// comments before it, and the line doc comments on the rows directly
453/// below it, which a line-comment tool reads as one block with it. The
454/// gathering comment does not bind forward, so `forward` drops it; it
455/// documents where it sits.
456fn bind_gathered<'a, T: Checker>(
457 stretch: &[Node<'a>],
458 code: &[u8],
459 gathers: fn(&Node, &[u8]) -> bool,
460 forward: impl Fn(&Node<'a>) -> bool,
461) -> Vec<Node<'a>> {
462 let Some(gatherer) = stretch
463 .iter()
464 .rposition(|n| T::is_doc_comment(n, code) && gathers(n, code))
465 else {
466 return Vec::new();
467 };
468 let line = |n: &Node| node_bytes(n, code).starts_with(b"//");
469 // Only a line-comment gatherer reads the line doc comments below it
470 // as one block with itself.
471 let gathers_below = line(&stretch[gatherer]);
472 let mut last = gatherer;
473 while let Some(below) = stretch.get(last + 1)
474 && gathers_below
475 && line(below)
476 && T::is_doc_comment(below, code)
477 && below.start_row() == stretch[last].end_row().saturating_add(1)
478 {
479 last += 1;
480 }
481 stretch[..=last].iter().copied().filter(forward).collect()
482}
483
484/// [`KeptDocs::Last`] over a stretch in source order: the last doc
485/// comment before the first skipped node — the declaration's first token —
486/// with the doc comments it joins, or else the first doc comment after it.
487fn bind_last<'a, T: Checker>(
488 stretch: &[Node<'a>],
489 code: &[u8],
490 joins: fn(&Node, &Node, &[u8]) -> bool,
491 forward: impl Fn(&Node<'a>) -> bool,
492) -> Vec<Node<'a>> {
493 let split = stretch
494 .iter()
495 .position(|n| !T::is_comment(n))
496 .unwrap_or(stretch.len());
497 let (before, after) = stretch.split_at(split);
498 let Some(last) = before.iter().rposition(&forward) else {
499 return after.iter().copied().find(forward).into_iter().collect();
500 };
501 joined_run(before, last, code, joins, forward)
502}
503
504/// [`KeptDocs::Leading`] over a stretch in source order: the members
505/// before the first token, read back past the hidden ones to the nearest
506/// other one, kept if it is a doc comment that binds forward, with the doc
507/// comments directly before it that it joins.
508fn bind_leading<'a, T: Checker>(
509 stretch: &[Node<'a>],
510 code: &[u8],
511 hidden: fn(&Node, &[u8]) -> bool,
512 joins: fn(&Node, &Node, &[u8]) -> bool,
513 forward: impl Fn(&Node<'a>) -> bool,
514) -> Vec<Node<'a>> {
515 let first_token = stretch
516 .iter()
517 .position(|n| !T::is_comment(n) && !hidden(n, code))
518 .unwrap_or(stretch.len());
519 let before = &stretch[..first_token];
520 let Some(last) = before.iter().rposition(|n| !hidden(n, code)) else {
521 return Vec::new();
522 };
523 if !forward(&before[last]) {
524 return Vec::new();
525 }
526 joined_run(before, last, code, joins, forward)
527}
528
529/// `before[last]` with the doc comments directly before it that it
530/// joins, in source order. `joins` is asked first: for a binding whose
531/// `joins` is [`never_joins`] it answers at once, where `forward`
532/// would scan the comment's bytes for nothing.
533fn joined_run<'a>(
534 before: &[Node<'a>],
535 last: usize,
536 code: &[u8],
537 joins: fn(&Node, &Node, &[u8]) -> bool,
538 forward: impl Fn(&Node<'a>) -> bool,
539) -> Vec<Node<'a>> {
540 let mut first = last;
541 while first > 0
542 && joins(&before[first - 1], &before[first], code)
543 && forward(&before[first - 1])
544 {
545 first -= 1;
546 }
547 before[first..=last].to_vec()
548}
549
550/// [`KeptDocs::Nearest`] over a stretch in source order whose last
551/// member `next` follows: the comment nearest the declaration that the
552/// tool can see, if it is a doc comment.
553fn bind_nearest<'a, T: Checker>(
554 stretch: &[Node<'a>],
555 next: Node<'a>,
556 hidden: fn(&Node, &Node) -> bool,
557 forward: impl Fn(&Node<'a>) -> bool,
558) -> Option<Node<'a>> {
559 let mut later = next;
560 for member in stretch.iter().rev() {
561 if T::is_comment(member) && !hidden(member, &later) {
562 return Some(*member).filter(forward);
563 }
564 later = *member;
565 }
566 None
567}
568
569/// Credits the rows of the comment run that `comment` ends, when the
570/// run is documentation: it sits directly above a node the language's
571/// [`Checker::is_doc_target`] accepts, or its first member opens a
572/// block per [`Checker::is_doc_run_opener`]. Called from a language's
573/// LOC comment arm for every comment; only the run's last member does
574/// any work beyond one sibling step, so a run of `k` rows costs `O(k)`
575/// sibling steps in total (#1597).
576///
577/// A run is the maximal chain of comment siblings on consecutive rows
578/// that hold nothing but comments; a trailing comment (`x := 1 // t`)
579/// is never a member and never seeds one, which the previous-sibling
580/// test decides — the `ploc` row set cannot, because code that opened a
581/// child space (`func A() {} // t`) lives in the child's stats. A blank
582/// row ends the run, as does anything that is not a comment; a comment
583/// the language says closes one ([`Checker::ends_doc_run`]) is its last
584/// member. The decision needs the row after the run, so it is made at
585/// the last member, which then walks back to credit the whole run through
586/// `credit(first_row, last_row)` per member, skipping the members
587/// [`Checker::is_doc_run_directive`] names (`//go:generate`, a Ruby
588/// shebang) — part of the group, not of the documentation.
589pub fn leading_doc_run<'a, T: Checker>(
590 comment: &Node<'a>,
591 code: &[u8],
592 ancestors: Ancestors<'a, '_>,
593 mut credit: impl FnMut(usize, usize),
594) {
595 let next = ancestors.siblings_after(comment).next();
596 if next
597 .as_ref()
598 .is_some_and(|n| run_continues_to::<T>(comment, n, code))
599 {
600 // A later member decides.
601 return;
602 }
603 let Some(first) = run_first_member::<T>(comment, code, ancestors) else {
604 return;
605 };
606 // `next` is `comment`'s sibling, so `ancestors` is its chain too.
607 let below = next.filter(|n| T::doc_target_start_row(n) == comment.end_row().saturating_add(1));
608 let documents = below.is_some_and(|n| T::is_doc_target(&n, code, ancestors))
609 || T::is_doc_run_opener(&first, below.as_ref(), code, ancestors);
610 if !documents {
611 return;
612 }
613 for member in std::iter::once(first).chain(ancestors.siblings_after(&first)) {
614 if member.start_byte() > comment.start_byte() {
615 break;
616 }
617 if !T::is_doc_run_directive(&member, code) {
618 credit(member.start_row(), member.end_row());
619 }
620 }
621}
622
623/// Whether `next`, the sibling after `comment`, is a later member of
624/// the same run: a comment on `comment`'s own row, or on the next row
625/// when `comment` does not end the run ([`Checker::ends_doc_run`]).
626/// Only `next` is tested as a comment, so `comment` must already be
627/// one: asked about a code node, it reports that the comment on the row
628/// below continues the code's run, which once let a backward scan run
629/// to the top of the file for every LDoc block (#1597).
630pub(crate) fn run_continues_to<T: Checker>(comment: &Node, next: &Node, code: &[u8]) -> bool {
631 T::is_comment(next)
632 && (next.start_row() <= comment.end_row()
633 || (next.start_row() == comment.end_row().saturating_add(1)
634 && !T::ends_doc_run(comment, code)))
635}
636
637/// The first member of the run `comment` ends: the comment siblings
638/// before it on consecutive rows that hold nothing but comments, so two
639/// comments sharing a row (`/* a */ /* b */`) are one row of the run.
640/// `None` when code precedes `comment` on its own row: a trailing
641/// comment belongs to no run, and a row where code precedes its
642/// comments ends the run below it. One backward pass over one sibling
643/// iterator.
644fn run_first_member<'a, T: Checker>(
645 comment: &Node<'a>,
646 code: &[u8],
647 ancestors: Ancestors<'a, '_>,
648) -> Option<Node<'a>> {
649 // `row_first` is the earliest comment found on the row being scanned;
650 // `first` is the first member of the earliest row known to be clean.
651 // Each step moves `row_first` to the sibling just before it, so one
652 // iterator walks the whole run.
653 let mut before = ancestors.siblings_before(comment);
654 let mut first = None;
655 let mut row_first = *comment;
656 loop {
657 match before.next() {
658 // Another token on this row: a comment extends the row, and
659 // code before it makes every comment on the row a trailing one.
660 Some(prev) if prev.end_row() >= row_first.start_row() => {
661 if !T::is_comment(&prev) {
662 return first;
663 }
664 row_first = prev;
665 }
666 // A comment ending on the row above: this row is clean, and
667 // the run continues upward unless that comment ends a run.
668 Some(prev)
669 if T::is_comment(&prev)
670 && prev.end_row().saturating_add(1) == row_first.start_row()
671 && !T::ends_doc_run(&prev, code) =>
672 {
673 first = Some(row_first);
674 row_first = prev;
675 }
676 _ => return Some(row_first),
677 }
678 }
679}
680
681/// The trailing comment that heads `first`'s LDoc group, when `first` sits
682/// directly under a row that ends in one: LDoc lexes a line comment with
683/// its newline and gathers every consecutive comment token into one group
684/// whose first token decides whether it is an LDoc block (`parse.lua`), so
685/// a `---` row under `x = 1 -- note` belongs to that `--` group. The run
686/// `leading_doc_run` hands over leaves such a comment out, as go/doc does,
687/// so it is looked up here.
688pub(crate) fn lua_group_head_above<'a, T: Checker>(
689 first: &Node<'a>,
690 code: &[u8],
691 ancestors: Ancestors<'a, '_>,
692) -> Option<Node<'a>> {
693 ancestors
694 .siblings_before(first)
695 .next()
696 .filter(|above| T::is_comment(above) && run_continues_to::<T>(above, first, code))
697}
698
699#[cfg(test)]
700mod tests {
701 use super::*;
702
703 /// Every language's `DOC_BINDING` spreads `..DocBinding::new(kept)`
704 /// and relies on its defaults: nothing skipped, every doc comment
705 /// binding forward, no gathering comment. Each const is evaluated at
706 /// compile time, so this is the one runtime call that pins them.
707 #[cfg(feature = "rust")]
708 #[test]
709 fn doc_binding_defaults_skip_nothing_and_bind_everything_forward() {
710 use crate::langs::RustCode;
711 use crate::node::Tree;
712 let source = b"/// d\nfn f() {}\n";
713 let tree = Tree::new::<RustCode>(source);
714 let comment = tree
715 .get_root()
716 .preorder()
717 .find(|node| RustCode::is_comment(node))
718 .expect("the fixture has a comment");
719 let binding = DocBinding::new(KeptDocs::All);
720 assert!(matches!(binding.kept, KeptDocs::All));
721 assert!(!(binding.skips)(&comment, Ancestors::unknown()));
722 assert!((binding.forward)(&comment, source, Ancestors::unknown()));
723 assert!(binding.gathers.is_none());
724 }
725
726 /// The walk back from a stretch's last comment reads past the parse
727 /// errors the scan forward from each member read past, so a member
728 /// whose scan stopped at the next comment is decided by the stretch
729 /// holding it. Not valid Rust — no qualifier may precede a doc comment
730 /// — but an error between two doc comments needs one, and a binding
731 /// that keeps every doc comment is where an undecided member shows. The
732 /// test pins that the two scans agree, not a reading of Rust.
733 #[cfg(feature = "rust")]
734 #[test]
735 fn both_scans_read_past_the_same_error() {
736 use crate::langs::RustCode;
737 use crate::node::Tree;
738 let source = b"unsafe extern \"C\" {\n /// a\n safe\n /// b\n fn g();\n}\n";
739 let tree = Tree::new::<RustCode>(source);
740 let comments: Vec<_> = tree
741 .get_root()
742 .preorder()
743 .filter(|node| RustCode::is_comment(node))
744 .collect();
745 assert_eq!(comments.len(), 2);
746 assert!(
747 tree.get_root().preorder().any(|node| node.is_error()),
748 "the fixture no longer parses `safe` as an error"
749 );
750 let mut credited = Vec::new();
751 for comment in &comments {
752 bound_doc_run::<RustCode>(comment, source, Ancestors::unknown(), |doc| {
753 credited.push(doc.start_row());
754 });
755 }
756 assert_eq!(credited, [1, 3]);
757 }
758
759 /// A wide parse `ERROR` holding a `package` — whose target test asks
760 /// for a *sibling* — is judged on a derived chain that lends no
761 /// `SiblingCache`, so the lookup seeks rather than asking a cache
762 /// that never recorded the error's children. Carrying the walk's
763 /// sibling cache onto the derived chain tripped the walk-must-record
764 /// assertion in `Ancestors::lookup` on this exact shape (#1686
765 /// review): a debug-build panic on malformed Java, where a release
766 /// build answered quietly. That half discriminates only through the
767 /// `debug_assert!`, so it is meaningful under `make pre-commit`'s
768 /// debug build and vacuous under `--release` (lesson #80).
769 ///
770 /// The gate's seek is counted too, in every build: one, for the one
771 /// package (#1871). Here the package is the error's first named
772 /// child, so the scan stops at it and the count cannot tell a gate
773 /// asked of every child from one asked of the packages alone;
774 /// `a_wide_error_s_children_ask_for_one_sibling_in_java` judges
775 /// every child for that.
776 #[cfg(feature = "java")]
777 #[test]
778 fn a_wide_error_s_package_is_judged_without_the_walk_s_sibling_cache() {
779 use crate::langs::JavaCode;
780 use crate::node::{FoldCache, SiblingCache, Tree, WIDE_PARENT, sibling_seeks};
781 // `class {` opens a body the stray `@`s never close, so recovery
782 // gathers the package and every `@` into one flat `ERROR`.
783 let source = format!(
784 "/** d */\nclass {{\npackage a;\n{}",
785 "@ \n".repeat(WIDE_PARENT + 40)
786 );
787 let tree = Tree::new::<JavaCode>(source.as_bytes());
788 let root = tree.get_root();
789 let error = root
790 .children()
791 .find(Node::is_error)
792 .expect("recovery leaves an ERROR under the root");
793 assert!(
794 error.child_count() > WIDE_PARENT,
795 "the ERROR must be wide, or the assertion this guards cannot fire"
796 );
797 assert!(
798 error
799 .children()
800 .any(|child| child.kind() == "package_declaration"),
801 "the ERROR must hold the package, whose target test seeks a sibling"
802 );
803
804 // What the walk lends: the root recorded, the ERROR not yet.
805 let chain = [root];
806 let mut siblings = SiblingCache::default();
807 siblings.record(&root, 0, root.children());
808 let folds = FoldCache::default();
809 let walk = Ancestors::known(&chain)
810 .with_siblings(&siblings)
811 .with_folds(&folds);
812 let before = sibling_seeks::observed();
813 assert!(
814 error_holds_target::<JavaCode>(&error, source.as_bytes(), walk),
815 "a package with no declaration after it is javadoc's target"
816 );
817 // expected: 1. Only a `package_declaration`'s gate asks for a
818 // sibling; the error holds one, and it is a target, so the scan
819 // of the error's children stops there.
820 assert_eq!(
821 sibling_seeks::observed() - before,
822 1,
823 "the package gate's one seek through the derived chain"
824 );
825 }
826
827 // What judging every named child of the parse error in `source`
828 // comes to, each as a doc target through the chain
829 // `error_holds_target` derives for them: the named children, how
830 // many are targets, and the uncached sibling lookups made. That
831 // helper stops at the first target; this asks every child, so a
832 // target test that came to ask for a sibling of each is counted
833 // once per child, where each ask seeks from the error's first.
834 #[cfg(any(
835 feature = "c",
836 feature = "cpp",
837 feature = "java",
838 feature = "mozcpp",
839 feature = "objc"
840 ))]
841 fn judge_every_child_of_the_error<T: Checker + crate::traits::LanguageInfo>(
842 source: &str,
843 ) -> (usize, usize, usize) {
844 use crate::node::{FoldCache, SiblingCache, Tree, WIDE_PARENT, sibling_seeks};
845 let code = source.as_bytes();
846 let tree = Tree::new::<T>(code);
847 let root = tree.get_root();
848 let error = root
849 .children()
850 .find(Node::is_error)
851 .expect("recovery leaves an ERROR under the root");
852 assert!(
853 error.child_count() > WIDE_PARENT,
854 "the ERROR must be wide: a seek under a narrow one is a short scan"
855 );
856 // What the walk lends: the root recorded, the ERROR not yet.
857 let chain = [root];
858 let mut siblings = SiblingCache::default();
859 siblings.record(&root, 0, root.children());
860 let folds = FoldCache::default();
861 let walk = Ancestors::known(&chain)
862 .with_siblings(&siblings)
863 .with_folds(&folds);
864 let under = walk.of_children(&error);
865 let named: Vec<_> = error.children().filter(Node::is_named).collect();
866 let before = sibling_seeks::observed();
867 let targets = named
868 .iter()
869 .filter(|child| T::is_doc_target(child, code, under.get()))
870 .count();
871 (named.len(), targets, sibling_seeks::observed() - before)
872 }
873
874 // The Doxygen fixture: an unclosed anonymous `struct {` (`class {`
875 // in the C++ grammars) makes recovery gather every field after it
876 // into one flat `ERROR`, each a `field_declaration` Doxygen
877 // documents.
878 #[cfg(any(feature = "c", feature = "cpp", feature = "mozcpp", feature = "objc"))]
879 fn doxygen_wide_error(opener: &str) -> String {
880 use crate::node::WIDE_PARENT;
881 format!(
882 "/** d */\n{opener} {{\n{}",
883 "int x;\n".repeat(WIDE_PARENT + 6)
884 )
885 }
886
887 // expected, for each Doxygen grammar below: `WIDE_PARENT + 6` named
888 // children, all of them targets, and no sibling asked for. No
889 // C-family `DocTarget` gate reads a sibling.
890 #[cfg(any(feature = "c", feature = "cpp", feature = "mozcpp", feature = "objc"))]
891 const DOXYGEN_JUDGED: (usize, usize, usize) = {
892 use crate::node::WIDE_PARENT;
893 (WIDE_PARENT + 6, WIDE_PARENT + 6, 0)
894 };
895
896 /// The children of a wide parse `ERROR` are judged as doc targets
897 /// through a derived chain, which lends no sibling record, so a
898 /// target test that asked for a sibling of each child would seek
899 /// from the error's first child every time. In the Doxygen grammars
900 /// none asks (#1871).
901 #[cfg(feature = "c")]
902 #[test]
903 fn a_wide_error_s_children_ask_for_no_sibling_in_c() {
904 let judged =
905 judge_every_child_of_the_error::<crate::langs::CCode>(&doxygen_wide_error("struct"));
906 assert_eq!(judged, DOXYGEN_JUDGED);
907 }
908
909 #[cfg(feature = "cpp")]
910 #[test]
911 fn a_wide_error_s_children_ask_for_no_sibling_in_cpp() {
912 let judged =
913 judge_every_child_of_the_error::<crate::langs::CppCode>(&doxygen_wide_error("class"));
914 assert_eq!(judged, DOXYGEN_JUDGED);
915 }
916
917 #[cfg(feature = "mozcpp")]
918 #[test]
919 fn a_wide_error_s_children_ask_for_no_sibling_in_mozcpp() {
920 let judged = judge_every_child_of_the_error::<crate::langs::MozcppCode>(
921 &doxygen_wide_error("class"),
922 );
923 assert_eq!(judged, DOXYGEN_JUDGED);
924 }
925
926 #[cfg(feature = "objc")]
927 #[test]
928 fn a_wide_error_s_children_ask_for_no_sibling_in_objc() {
929 let judged =
930 judge_every_child_of_the_error::<crate::langs::ObjcCode>(&doxygen_wide_error("struct"));
931 assert_eq!(judged, DOXYGEN_JUDGED);
932 }
933
934 /// Java's `DocTarget` row holds the one gate found to ask for a
935 /// sibling through this chain, the package's. With the package
936 /// after `WIDE_PARENT` local declarations, none of them a target,
937 /// every child is judged and the package's ask is the only one: a
938 /// gate asked of each child would count one per child here (#1871).
939 #[cfg(feature = "java")]
940 #[test]
941 fn a_wide_error_s_children_ask_for_one_sibling_in_java() {
942 use crate::node::WIDE_PARENT;
943 let source = format!(
944 "/** d */\nclass {{\n{}package a;\n@ \n",
945 "int x;\n".repeat(WIDE_PARENT)
946 );
947 let judged = judge_every_child_of_the_error::<crate::langs::JavaCode>(&source);
948 // expected: the `WIDE_PARENT` locals and the package; the package
949 // alone is a target; its gate's one seek for what follows it.
950 assert_eq!(judged, (WIDE_PARENT + 1, 1, 1));
951 }
952
953 /// A nest of Doxygen conditionals under a parse `ERROR`, asked the
954 /// way a stretch asks — `read_past_error` judges the error's
955 /// children on a chain *derived* from the walk's — reads each
956 /// conditional once per walk, as the same nest does outside an
957 /// error. The derived chain used to be rebuilt with
958 /// `Ancestors::known`, which carries no cache, so the nest was read
959 /// `O(depth²)` on every walk despite the memo (#1686 review, lesson
960 /// 101). Rebuilding it that way again fails the memoised count.
961 #[cfg(feature = "c")]
962 #[test]
963 fn an_error_s_conditionals_are_read_through_the_walk_s_memo() {
964 use crate::lang_helpers::doxygen::conditionals_read;
965 use crate::langs::CCode;
966 use crate::node::{FoldCache, Tree};
967 const DEPTH: usize = 40;
968 // An unclosed anonymous `struct {` makes recovery wrap everything
969 // after it in one `ERROR` whose only named child is the outermost
970 // conditional — a tag name would be a second and make the error
971 // itself a target (`no_entry_inside`). The nest's bottom holds no
972 // declaration, so the error holds no target and is read past.
973 let source = format!(
974 "struct {{\n{}#include <x.h>\n{}",
975 "/** d */\n#ifdef A\n".repeat(DEPTH),
976 "#endif\n".repeat(DEPTH)
977 );
978 let tree = Tree::new::<CCode>(source.as_bytes());
979 let root = tree.get_root();
980 let error = root
981 .children()
982 .find(Node::is_error)
983 .expect("recovery leaves an ERROR under the root");
984 let nested = error
985 .children()
986 .filter(|child| crate::lang_helpers::doxygen::preproc_conditional::<CCode>(child))
987 .count();
988 assert_eq!(
989 nested, 1,
990 "the outermost conditional sits directly under the ERROR"
991 );
992
993 let cache = FoldCache::default();
994 let chain = [root];
995 let walk = Ancestors::known(&chain).with_folds(&cache);
996 let before = conditionals_read::observed();
997 for _ in 0..DEPTH {
998 assert!(
999 read_past_error::<CCode>(&error, source.as_bytes(), walk),
1000 "an ERROR holding no target is read past"
1001 );
1002 }
1003 assert_eq!(
1004 conditionals_read::observed() - before,
1005 DEPTH,
1006 "each conditional under the ERROR is read once per walk, however \
1007 often the error is asked about"
1008 );
1009
1010 let before = conditionals_read::observed();
1011 assert!(read_past_error::<CCode>(
1012 &error,
1013 source.as_bytes(),
1014 Ancestors::known(&chain)
1015 ));
1016 assert_eq!(
1017 conditionals_read::observed() - before,
1018 DEPTH,
1019 "one unmemoised ask reads the whole nest once"
1020 );
1021 }
1022}