Skip to main content

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(&current) {
154            continue;
155        }
156        if current.child_count() == 0 {
157            spelling.extend(
158                node_bytes(&current, 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}