pub(crate) use super::doc_text::{
csharp_doc, doxygen, go_directive, java_doc, javadoc_block, jsdoc_virtual, kotlin_doc,
ldoc_opener, lua_long_comment, phpdoc, pod_comment_region, ruby_directive_opener,
ruby_magic_comment, tsdoc_block, tsdoc_module,
};
use crate::checker::Checker;
use crate::node::{Ancestors, FoldLane, Node};
#[derive(Clone, Copy, Debug)]
pub struct DocBinding {
pub kept: KeptDocs,
pub skips: for<'a, 'b> fn(&Node<'a>, Ancestors<'a, 'b>) -> bool,
pub forward: for<'a, 'b> fn(&Node<'a>, &[u8], Ancestors<'a, 'b>) -> bool,
pub gathers: Option<fn(&Node, &[u8]) -> bool>,
}
impl DocBinding {
#[must_use]
pub const fn new(kept: KeptDocs) -> Self {
Self {
kept,
skips: |_, _| false,
forward: |_, _, _| true,
gathers: None,
}
}
}
#[derive(Clone, Copy, Debug)]
pub enum KeptDocs {
All,
Last {
joins: fn(&Node, &Node, &[u8]) -> bool,
},
Nearest {
hidden: fn(&Node, &Node) -> bool,
},
Leading {
hidden: fn(&Node, &[u8]) -> bool,
joins: fn(&Node, &Node, &[u8]) -> bool,
after_code: fn(&Node) -> bool,
},
}
#[must_use]
pub(crate) fn never_joins(_: &Node, _: &Node, _: &[u8]) -> bool {
false
}
#[inline]
#[must_use]
pub(crate) fn node_bytes<'a>(node: &Node, code: &'a [u8]) -> &'a [u8] {
code.get(node.start_byte()..node.end_byte()).unwrap_or(&[])
}
#[must_use]
pub(crate) fn outside_function_bodies<'a, T: Checker>(
comment: &Node<'a>,
ancestors: Ancestors<'a, '_>,
) -> bool {
!held_in_body::<T>(comment, 0, ancestors)
}
fn held_in_body<'a, T: Checker>(
node: &Node<'a>,
skip: usize,
ancestors: Ancestors<'a, '_>,
) -> bool {
ancestors.fold_down(
node,
skip,
FoldLane::DocInBody,
0,
|held, ancestor, outer, below| {
u8::from(held != 0 || T::holds_doc_comment_in_body(ancestor, outer, below))
},
) != 0
}
#[must_use]
pub fn documents_where_it_sits<'a, T: Checker>(
node: &Node<'a>,
code: &[u8],
ancestors: Ancestors<'a, '_>,
) -> bool {
if T::DOC_COMMENTS_IN_FUNCTION_BODIES {
return true;
}
let mut below = *node;
for (ancestor, outer) in ancestors.iter(node).take(2) {
if T::holds_doc_comment_in_body(&ancestor, outer, &below)
&& !T::doc_comment_opens_body(node, &ancestor, &below, code)
{
return false;
}
below = ancestor;
}
!held_in_body::<T>(node, 2, ancestors)
}
#[must_use]
pub fn documents_unbound<'a, T: Checker>(
comment: &Node<'a>,
code: &[u8],
ancestors: Ancestors<'a, '_>,
) -> bool {
T::DOC_BINDING.is_none_or(|binding| !(binding.forward)(comment, code, ancestors))
}
pub fn bound_doc_run<'a, T: Checker>(
comment: &Node<'a>,
code: &[u8],
ancestors: Ancestors<'a, '_>,
mut credit: impl FnMut(&Node<'a>),
) {
let Some(binding) = T::DOC_BINDING else {
return;
};
let end = match stretch_end::<T>(comment, code, ancestors, binding.skips) {
StretchEnd::Undecided => return,
StretchEnd::Elsewhere if binding.gathers.is_none() => return,
end => end,
};
if !documents_where_it_sits::<T>(comment, code, ancestors) {
return;
}
let (stretch, code_before) = collect_stretch::<T>(comment, code, ancestors, binding.skips);
let forward =
|n: &Node<'a>| T::is_doc_comment(n, code) && (binding.forward)(n, code, ancestors);
let StretchEnd::AtTarget { next, target } = end else {
if let Some(gathers) = binding.gathers {
bind_gathered::<T>(&stretch, code, gathers, forward)
.iter()
.for_each(&mut credit);
}
return;
};
let kept = match binding.kept {
KeptDocs::All => stretch.iter().copied().filter(forward).collect(),
KeptDocs::Last { joins } => bind_last::<T>(&stretch, code, joins, forward),
KeptDocs::Nearest { hidden } => bind_nearest::<T>(&stretch, next, hidden, forward)
.into_iter()
.collect(),
KeptDocs::Leading {
hidden,
joins,
after_code,
} => {
let after_code_row = code_before
.filter(|_| !after_code(&target))
.map(|before| before.end_row());
let attaches = |n: &Node<'a>| forward(n) && Some(n.start_row()) != after_code_row;
bind_leading::<T>(&stretch, code, hidden, joins, attaches)
}
};
kept.iter().for_each(&mut credit);
}
enum StretchEnd<'a> {
Undecided,
AtTarget { next: Node<'a>, target: Node<'a> },
Elsewhere,
}
fn stretch_end<'a, T: Checker>(
comment: &Node<'a>,
code: &[u8],
ancestors: Ancestors<'a, '_>,
skips: for<'b> fn(&Node<'a>, Ancestors<'a, 'b>) -> bool,
) -> StretchEnd<'a> {
let mut after = ancestors.siblings_after(comment).peekable();
let Some(&next) = after.peek() else {
return StretchEnd::Elsewhere;
};
match after.find(|n| !skips(n, ancestors) && !read_past_error::<T>(n, code, ancestors)) {
Some(target) if T::is_comment(&target) => StretchEnd::Undecided,
Some(target)
if T::is_doc_target(&target, code, ancestors)
|| (target.is_error() && error_holds_target::<T>(&target, code, ancestors)) =>
{
StretchEnd::AtTarget { next, target }
}
_ => StretchEnd::Elsewhere,
}
}
fn collect_stretch<'a, T: Checker>(
comment: &Node<'a>,
code: &[u8],
ancestors: Ancestors<'a, '_>,
skips: for<'b> fn(&Node<'a>, Ancestors<'a, 'b>) -> bool,
) -> (Vec<Node<'a>>, Option<Node<'a>>) {
let mut stretch = vec![*comment];
let mut before = None;
for sibling in ancestors
.siblings_before(comment)
.filter(|sibling| !read_past_error::<T>(sibling, code, ancestors))
{
if T::is_comment(&sibling) || skips(&sibling, ancestors) {
stretch.push(sibling);
} else {
before = Some(sibling);
break;
}
}
stretch.reverse();
(stretch, before)
}
fn read_past_error<'a, T: Checker>(
node: &Node<'a>,
code: &[u8],
ancestors: Ancestors<'a, '_>,
) -> bool {
node.is_error()
&& !T::is_doc_target(node, code, ancestors)
&& !error_holds_target::<T>(node, code, ancestors)
}
fn error_holds_target<'a, T: Checker>(
error: &Node<'a>,
code: &[u8],
ancestors: Ancestors<'a, '_>,
) -> bool {
let chain = ancestors.children_chain(error);
let inside = chain
.as_deref()
.map_or_else(Ancestors::unknown, |chain| ancestors.below(chain));
error
.children()
.any(|child| child.is_named() && T::is_doc_target(&child, code, inside))
}
fn bind_gathered<'a, T: Checker>(
stretch: &[Node<'a>],
code: &[u8],
gathers: fn(&Node, &[u8]) -> bool,
forward: impl Fn(&Node<'a>) -> bool,
) -> Vec<Node<'a>> {
let Some(gatherer) = stretch
.iter()
.rposition(|n| T::is_doc_comment(n, code) && gathers(n, code))
else {
return Vec::new();
};
let line = |n: &Node| node_bytes(n, code).starts_with(b"//");
let gathers_below = line(&stretch[gatherer]);
let mut last = gatherer;
while let Some(below) = stretch.get(last + 1)
&& gathers_below
&& line(below)
&& T::is_doc_comment(below, code)
&& below.start_row() == stretch[last].end_row().saturating_add(1)
{
last += 1;
}
stretch[..=last].iter().copied().filter(forward).collect()
}
fn bind_last<'a, T: Checker>(
stretch: &[Node<'a>],
code: &[u8],
joins: fn(&Node, &Node, &[u8]) -> bool,
forward: impl Fn(&Node<'a>) -> bool,
) -> Vec<Node<'a>> {
let split = stretch
.iter()
.position(|n| !T::is_comment(n))
.unwrap_or(stretch.len());
let (before, after) = stretch.split_at(split);
let Some(last) = before.iter().rposition(&forward) else {
return after.iter().copied().find(forward).into_iter().collect();
};
joined_run(before, last, code, joins, forward)
}
fn bind_leading<'a, T: Checker>(
stretch: &[Node<'a>],
code: &[u8],
hidden: fn(&Node, &[u8]) -> bool,
joins: fn(&Node, &Node, &[u8]) -> bool,
forward: impl Fn(&Node<'a>) -> bool,
) -> Vec<Node<'a>> {
let first_token = stretch
.iter()
.position(|n| !T::is_comment(n) && !hidden(n, code))
.unwrap_or(stretch.len());
let before = &stretch[..first_token];
let Some(last) = before.iter().rposition(|n| !hidden(n, code)) else {
return Vec::new();
};
if !forward(&before[last]) {
return Vec::new();
}
joined_run(before, last, code, joins, forward)
}
fn joined_run<'a>(
before: &[Node<'a>],
last: usize,
code: &[u8],
joins: fn(&Node, &Node, &[u8]) -> bool,
forward: impl Fn(&Node<'a>) -> bool,
) -> Vec<Node<'a>> {
let mut first = last;
while first > 0
&& joins(&before[first - 1], &before[first], code)
&& forward(&before[first - 1])
{
first -= 1;
}
before[first..=last].to_vec()
}
fn bind_nearest<'a, T: Checker>(
stretch: &[Node<'a>],
next: Node<'a>,
hidden: fn(&Node, &Node) -> bool,
forward: impl Fn(&Node<'a>) -> bool,
) -> Option<Node<'a>> {
let mut later = next;
for member in stretch.iter().rev() {
if T::is_comment(member) && !hidden(member, &later) {
return Some(*member).filter(forward);
}
later = *member;
}
None
}
pub fn leading_doc_run<'a, T: Checker>(
comment: &Node<'a>,
code: &[u8],
ancestors: Ancestors<'a, '_>,
mut credit: impl FnMut(usize, usize),
) {
let next = ancestors.siblings_after(comment).next();
if next
.as_ref()
.is_some_and(|n| run_continues_to::<T>(comment, n, code))
{
return;
}
let Some(first) = run_first_member::<T>(comment, code, ancestors) else {
return;
};
let below = next.filter(|n| T::doc_target_start_row(n) == comment.end_row().saturating_add(1));
let documents = below.is_some_and(|n| T::is_doc_target(&n, code, ancestors))
|| T::is_doc_run_opener(&first, below.as_ref(), code, ancestors);
if !documents {
return;
}
for member in std::iter::once(first).chain(ancestors.siblings_after(&first)) {
if member.start_byte() > comment.start_byte() {
break;
}
if !T::is_doc_run_directive(&member, code) {
credit(member.start_row(), member.end_row());
}
}
}
pub(crate) fn run_continues_to<T: Checker>(comment: &Node, next: &Node, code: &[u8]) -> bool {
T::is_comment(next)
&& (next.start_row() <= comment.end_row()
|| (next.start_row() == comment.end_row().saturating_add(1)
&& !T::ends_doc_run(comment, code)))
}
fn run_first_member<'a, T: Checker>(
comment: &Node<'a>,
code: &[u8],
ancestors: Ancestors<'a, '_>,
) -> Option<Node<'a>> {
let mut before = ancestors.siblings_before(comment);
let mut first = None;
let mut row_first = *comment;
loop {
match before.next() {
Some(prev) if prev.end_row() >= row_first.start_row() => {
if !T::is_comment(&prev) {
return first;
}
row_first = prev;
}
Some(prev)
if T::is_comment(&prev)
&& prev.end_row().saturating_add(1) == row_first.start_row()
&& !T::ends_doc_run(&prev, code) =>
{
first = Some(row_first);
row_first = prev;
}
_ => return Some(row_first),
}
}
}
pub(crate) fn lua_group_head_above<'a, T: Checker>(
first: &Node<'a>,
code: &[u8],
ancestors: Ancestors<'a, '_>,
) -> Option<Node<'a>> {
ancestors
.siblings_before(first)
.next()
.filter(|above| T::is_comment(above) && run_continues_to::<T>(above, first, code))
}
#[cfg(test)]
mod tests {
use super::*;
#[cfg(feature = "rust")]
#[test]
fn doc_binding_defaults_skip_nothing_and_bind_everything_forward() {
use crate::langs::RustCode;
use crate::node::Tree;
let source = b"/// d\nfn f() {}\n";
let tree = Tree::new::<RustCode>(source);
let comment = tree
.get_root()
.preorder()
.find(|node| RustCode::is_comment(node))
.expect("the fixture has a comment");
let binding = DocBinding::new(KeptDocs::All);
assert!(matches!(binding.kept, KeptDocs::All));
assert!(!(binding.skips)(&comment, Ancestors::unknown()));
assert!((binding.forward)(&comment, source, Ancestors::unknown()));
assert!(binding.gathers.is_none());
}
#[cfg(feature = "rust")]
#[test]
fn both_scans_read_past_the_same_error() {
use crate::langs::RustCode;
use crate::node::Tree;
let source = b"unsafe extern \"C\" {\n /// a\n safe\n /// b\n fn g();\n}\n";
let tree = Tree::new::<RustCode>(source);
let comments: Vec<_> = tree
.get_root()
.preorder()
.filter(|node| RustCode::is_comment(node))
.collect();
assert_eq!(comments.len(), 2);
assert!(
tree.get_root().preorder().any(|node| node.is_error()),
"the fixture no longer parses `safe` as an error"
);
let mut credited = Vec::new();
for comment in &comments {
bound_doc_run::<RustCode>(comment, source, Ancestors::unknown(), |doc| {
credited.push(doc.start_row());
});
}
assert_eq!(credited, [1, 3]);
}
#[cfg(feature = "java")]
#[test]
fn a_wide_error_s_package_is_judged_without_the_walk_s_sibling_cache() {
use crate::langs::JavaCode;
use crate::node::{FoldCache, SiblingCache, Tree, WIDE_PARENT};
let source = format!(
"/** d */\nclass {{\npackage a;\n{}",
"@ \n".repeat(WIDE_PARENT + 40)
);
let tree = Tree::new::<JavaCode>(source.as_bytes());
let root = tree.get_root();
let error = root
.children()
.find(Node::is_error)
.expect("recovery leaves an ERROR under the root");
assert!(
error.child_count() > WIDE_PARENT,
"the ERROR must be wide, or the assertion this guards cannot fire"
);
assert!(
error
.children()
.any(|child| child.kind() == "package_declaration"),
"the ERROR must hold the package, whose target test seeks a sibling"
);
let chain = [root];
let mut siblings = SiblingCache::default();
siblings.record(&root, 0, root.children());
let folds = FoldCache::default();
let walk = Ancestors::known(&chain)
.with_siblings(&siblings)
.with_folds(&folds);
assert!(
error_holds_target::<JavaCode>(&error, source.as_bytes(), walk),
"a package with no declaration after it is javadoc's target"
);
}
#[cfg(feature = "c")]
#[test]
fn an_error_s_conditionals_are_read_through_the_walk_s_memo() {
use crate::lang_helpers::doxygen::conditionals_read;
use crate::langs::CCode;
use crate::node::{FoldCache, Tree};
const DEPTH: usize = 40;
let source = format!(
"struct {{\n{}#include <x.h>\n{}",
"/** d */\n#ifdef A\n".repeat(DEPTH),
"#endif\n".repeat(DEPTH)
);
let tree = Tree::new::<CCode>(source.as_bytes());
let root = tree.get_root();
let error = root
.children()
.find(Node::is_error)
.expect("recovery leaves an ERROR under the root");
let nested = error
.children()
.filter(|child| crate::lang_helpers::doxygen::preproc_conditional::<CCode>(child))
.count();
assert_eq!(
nested, 1,
"the outermost conditional sits directly under the ERROR"
);
let cache = FoldCache::default();
let chain = [root];
let walk = Ancestors::known(&chain).with_folds(&cache);
let before = conditionals_read::observed();
for _ in 0..DEPTH {
assert!(
read_past_error::<CCode>(&error, source.as_bytes(), walk),
"an ERROR holding no target is read past"
);
}
assert_eq!(
conditionals_read::observed() - before,
DEPTH,
"each conditional under the ERROR is read once per walk, however \
often the error is asked about"
);
let before = conditionals_read::observed();
assert!(read_past_error::<CCode>(
&error,
source.as_bytes(),
Ancestors::known(&chain)
));
assert_eq!(
conditionals_read::observed() - before,
DEPTH,
"one unmemoised ask reads the whole nest once"
);
}
}