use crate::checker::Checker;
use crate::lang_helpers::doc_comment::{node_bytes, outside_function_bodies};
use crate::node::{Ancestors, MemoQuestion, Node, NodeMemo};
#[inline]
#[must_use]
pub(crate) fn doxygen_member_after(s: &[u8]) -> bool {
[&b"/**<"[..], b"/*!<", b"///<", b"//!<"]
.iter()
.any(|marker| s.starts_with(marker))
}
#[must_use]
pub(crate) fn doxygen_standalone(s: &[u8]) -> bool {
const ALWAYS: &[&[u8]] = &[
b"file",
b"mainpage",
b"page",
b"dir",
b"example",
b"defgroup",
b"addtogroup",
b"weakgroup",
b"name",
b"package",
];
const NAMED: &[&[u8]] = &[
b"fn",
b"var",
b"def",
b"typedef",
b"property",
b"overload",
b"enum",
b"struct",
b"union",
b"class",
b"namespace",
b"interface",
b"protocol",
b"concept",
b"idlexcept",
b"module",
];
let mut at = 0;
while at < s.len() {
if let Some(end) = literal_end(s, at) {
at = end;
continue;
}
let Some(word) = doxygen_command(s, at) else {
at += 1;
continue;
};
at += 1 + word.len();
if ALWAYS.contains(&word) || (NAMED.contains(&word) && names_something(&s[at..])) {
return true;
}
}
false
}
fn literal_end(s: &[u8], at: usize) -> Option<usize> {
let rest = &s[at..];
if let Some(end) = delimited_end(s, at) {
return Some(end);
}
if let Some(span) = rest.strip_prefix(b"`") {
return code_span_close(span).map(|close| at + close + 2);
}
if let Some(quoted) = rest.strip_prefix(b"\"") {
return quoted_text_close(quoted).map(|close| at + close + 2);
}
if matches!(rest, [b'@', b'@', ..] | [b'\\', b'\\', ..]) {
return Some(at + 2);
}
format_block_end(s, at)
}
fn delimited_end(s: &[u8], at: usize) -> Option<usize> {
let rest = &s[at..];
if rest.starts_with(b"<!--") {
return Some(html_comment_end(s, at + 4));
}
let (open, close): (&[u8], &[u8]) = if rest.starts_with(b"```") {
(b"```", b"```")
} else if rest.starts_with(b"<![CDATA[") {
(b"<![CDATA[", b"]]>")
} else {
return None;
};
let body = at + open.len();
let found = s[body..].windows(close.len()).position(|w| w == close);
Some(found.map_or(s.len(), |found| body + found + close.len()))
}
fn quoted_text_close(quoted: &[u8]) -> Option<usize> {
quoted
.iter()
.position(|&b| b == b'"' || b == b'\n')
.filter(|&close| quoted[close] == b'"')
}
const FORMAT_BLOCKS: &[(&[u8], &[u8])] = &[
(b"code", b"endcode"),
(b"icode", b"endicode"),
(b"verbatim", b"endverbatim"),
(b"iverbatim", b"endiverbatim"),
(b"iliteral", b"endiliteral"),
(b"htmlonly", b"endhtmlonly"),
(b"latexonly", b"endlatexonly"),
(b"xmlonly", b"endxmlonly"),
(b"rtfonly", b"endrtfonly"),
(b"manonly", b"endmanonly"),
(b"docbookonly", b"enddocbookonly"),
(b"dot", b"enddot"),
(b"msc", b"endmsc"),
(b"startuml", b"enduml"),
];
fn format_block_end(s: &[u8], at: usize) -> Option<usize> {
let word = doxygen_command(s, at)?;
let (_, end) = FORMAT_BLOCKS.iter().find(|(open, _)| *open == word)?;
Some(block_end(s, at, end))
}
fn code_span_close(span: &[u8]) -> Option<usize> {
let mut start = 0;
for (index, line) in span.split(|&b| b == b'\n').enumerate() {
if let Some(close) = line.iter().position(|&b| b == b'`') {
return Some(start + close);
}
let text = line.trim_ascii();
if index > 0
&& text
.strip_prefix(b"*")
.unwrap_or(text)
.trim_ascii()
.is_empty()
{
return None;
}
start += line.len() + 1;
}
None
}
fn html_comment_end(s: &[u8], from: usize) -> usize {
(from..s.len())
.find(|&at| s[at..].starts_with(b"-->") && (at == from || s[at - 1] != b'-'))
.map_or(s.len(), |at| at + 3)
}
fn block_end(s: &[u8], at: usize, end: &[u8]) -> usize {
(at + 1..s.len())
.find(|&after| doxygen_command(s, after) == Some(end))
.map_or(s.len(), |after| after + 1 + end.len())
}
fn names_something(after: &[u8]) -> bool {
let line = after.split(|&b| b == b'\n').next().unwrap_or_default();
let line = line.trim_ascii();
!line
.strip_suffix(b"*/")
.unwrap_or(line)
.trim_ascii()
.is_empty()
}
fn doxygen_command(s: &[u8], at: usize) -> Option<&[u8]> {
if !matches!(s.get(at), Some(b'@' | b'\\')) {
return None;
}
let rest = &s[at + 1..];
let len = rest
.iter()
.take_while(|b| b.is_ascii_alphabetic() || **b == b'_')
.count();
if len == 0 {
return None;
}
let mail = s[at] == b'@'
&& at > 0
&& s[at - 1].is_ascii_alphanumeric()
&& rest
.iter()
.take_while(|b| b.is_ascii_alphanumeric() || matches!(b, b'-' | b'.'))
.skip(len)
.any(|&b| b == b'.');
(!mail).then(|| &rest[..len])
}
#[must_use]
pub(crate) fn preproc_conditional<T: DoxygenRow>(node: &Node) -> bool {
T::conditional_kind(node.kind_id())
}
crate::observation::counter!(conditionals_read);
#[must_use]
pub(crate) fn conditional_declares<T: DoxygenRow>(node: &Node, ancestors: Ancestors) -> bool {
let unshared = NodeMemo::default();
let memo = ancestors
.node_memo(MemoQuestion::ConditionalDeclares)
.unwrap_or(&unshared);
if let Some(answer) = memo.get(node) {
return answer;
}
let mut answers = Vec::new();
let mut stack = vec![Visit::Read {
conditional: *node,
outer: None,
}];
while let Some(visit) = stack.pop() {
match visit {
Visit::Read { conditional, outer } => {
conditionals_read::record();
let own = answers.len();
stack.push(Visit::Answer {
conditional,
outer,
own,
});
answers.push(children_declare::<T>(
&conditional,
ancestors,
memo,
|nested| {
stack.push(Visit::Read {
conditional: nested,
outer: Some(own),
});
},
));
}
Visit::Answer {
conditional,
outer,
own,
} => {
memo.set(&conditional, answers[own]);
if let Some(outer) = outer {
answers[outer] |= answers[own];
}
}
}
}
memo.get(node) == Some(true)
}
enum Visit<'a> {
Read {
conditional: Node<'a>,
outer: Option<usize>,
},
Answer {
conditional: Node<'a>,
outer: Option<usize>,
own: usize,
},
}
fn children_declare<'a, T: DoxygenRow>(
conditional: &Node<'a>,
ancestors: Ancestors<'a, '_>,
memo: &NodeMemo,
mut defer: impl FnMut(Node<'a>),
) -> bool {
let parent = [*conditional];
let below = chain_below(ancestors, &parent);
let mut declares = false;
for child in conditional.children() {
if preproc_conditional::<T>(&child) {
match memo.get(&child) {
Some(answer) => declares |= answer,
None => defer(child),
}
} else if !declares {
declares = non_conditional_entry::<T>(&child, below);
}
}
declares
}
fn chain_below<'a, 'c>(
ancestors: Ancestors<'a, 'c>,
parent: &'c [Node<'a>; 1],
) -> Ancestors<'a, 'c> {
if ancestors.is_known() {
ancestors.below(parent)
} else {
ancestors
}
}
#[must_use]
pub(crate) fn doxygen_container<T: DoxygenRow>(node: &Node) -> bool {
preproc_conditional::<T>(node)
|| matches!(
node.kind(),
"translation_unit"
| "template_parameter_list"
| "declaration_list"
| "field_declaration_list"
| "enumerator_list"
| "class_interface"
| "class_implementation"
| "protocol_declaration"
| "qualified_protocol_interface_declaration"
| "instance_variables"
)
}
#[must_use]
pub(crate) fn doxygen_skips<T: DoxygenRow>(node: &Node, ancestors: Ancestors) -> bool {
match node.kind() {
"preproc_include"
| "preproc_call"
| "static_assert_declaration"
| "namespace_alias_definition"
| "access_specifier"
| "alone_macro"
| ":"
| ";" => true,
"expression_statement" => !statement_is_macro_call(node),
"ERROR" => no_entry_inside::<T>(node, ancestors),
_ => preproc_conditional::<T>(node) && !conditional_declares::<T>(node, ancestors),
}
}
pub(crate) fn no_entry_inside<T: DoxygenRow>(error: &Node, ancestors: Ancestors) -> bool {
let mut named = error
.children()
.filter(|child| child.is_named() && !child.is_error() && child.kind() != "comment");
match (named.next(), named.next()) {
(None, _) => true,
(Some(only), None) => {
let parent = [*error];
!doxygen_entry::<T>(&only, chain_below(ancestors, &parent))
}
_ => false,
}
}
fn unterminated(statement: &Node) -> bool {
statement.children().last().is_some_and(|c| c.is_missing())
}
#[must_use]
pub(crate) fn statement_is_macro_call(statement: &Node) -> bool {
statement.child_count() > 1 && !unterminated(statement)
}
#[must_use]
pub(crate) fn doxygen_target<'a, T: DoxygenRow>(
node: &Node<'a>,
code: &[u8],
ancestors: Ancestors<'a, '_>,
) -> bool {
T::doc_target_row(node, code, ancestors)
|| (node.is_error() && !no_entry_inside::<T>(node, ancestors))
}
fn doxygen_entry<T: DoxygenRow>(node: &Node, ancestors: Ancestors) -> bool {
!preproc_conditional::<T>(node) && non_conditional_entry::<T>(node, ancestors)
}
fn non_conditional_entry<T: DoxygenRow>(node: &Node, ancestors: Ancestors) -> bool {
if node.is_error() {
return !no_entry_inside::<T>(node, ancestors);
}
T::doc_target_row(node, &[], ancestors)
}
pub(crate) trait DoxygenRow {
fn doc_target_row<'a>(node: &Node<'a>, code: &[u8], ancestors: Ancestors<'a, '_>) -> bool;
fn conditional_kind(kind: u16) -> bool;
}
#[must_use]
pub(crate) fn doxygen_binds_forward<'a, T: Checker + DoxygenRow>(
comment: &Node<'a>,
code: &[u8],
ancestors: Ancestors<'a, '_>,
) -> bool {
let bytes = node_bytes(comment, code);
!doxygen_member_after(bytes)
&& !doxygen_standalone(bytes)
&& ancestors
.parent(comment)
.is_some_and(|parent| doxygen_container::<T>(&parent))
&& outside_function_bodies::<T>(comment, ancestors)
}
#[cfg(test)]
mod tests {
use super::*;
const STANDALONE: &[&[u8]] = &[
b"/** @file */",
b"/*! \\file x.c */",
b"/// @file",
b"/**\n *@file\n */",
b"/**\n * text\n * @file\n */",
b"/** <tt>@file</tt> */",
b"/** foo@file here */",
b"/** @mainpage */",
b"/** @page p Title */",
b"/** @dir */",
b"/** @example */",
b"/** @defgroup */",
b"/** @addtogroup g */",
b"/** @weakgroup */",
b"/** @name */",
b"/** @package */",
b"/** @class X */",
b"/** @struct S\n * d */",
b"/** @def M */",
b"/** @fn int f(void) */",
b"/** d @fn int f(void) */",
b"/** @namespace n */",
b"/** @concept K */",
b"/**\n * @code\n * x\n * @endcode\n * @file\n */",
b"/**\n * ```\n * x\n * ```\n * @file\n */",
b"/**\n * @verbatim x @endverbatim @file\n */",
b"/**\n * @htmlonly x @endhtmlonly\n * @file\n */",
b"/**\n * <!-- x -->\n * @file\n */",
b"/** `a` @file x `b` */",
b"/** `a\n *\n * @file x\n * b` */",
b"/** `a\n * @file x\n */",
b"/** @defgroup g.x G */",
b"/** (@defgroup g.x G) */",
b"/** a\\defgroup g.x G */",
b"/** a\\defgroup.g G */",
b"/** x @defgroup.g G */",
b"/** @var v */",
b"/** @typedef t */",
b"/** @property p */",
b"/** @overload void f(int) */",
b"/** @enum e */",
b"/** @union u */",
b"/** @interface I */",
b"/** @protocol P */",
b"/** @idlexcept E */",
b"/** @module m */",
b"/** @icode x @endicode @file */",
b"/** @iverbatim x @endiverbatim @file */",
b"/** @iliteral x @endiliteral @file */",
b"/** @latexonly x @endlatexonly @file */",
b"/** @xmlonly x @endxmlonly @file */",
b"/** @rtfonly x @endrtfonly @file */",
b"/** @manonly x @endmanonly @file */",
b"/** @docbookonly x @enddocbookonly @file */",
b"/** @dot x @enddot @file */",
b"/** @msc x @endmsc @file */",
b"/** @startuml x @enduml @file */",
b"/** <!-- x -->@file */",
b"/** \"@file */",
b"/** \"a\"\n * @file\n */",
b"/** \"x\n * @file\" */",
b"/** \"\"@file */",
b"/** <![CDATA[ x ]]> @file */",
b"/** <![CDATA[ x ]]>@file */",
];
const ATTACHED: &[&[u8]] = &[
b"/** d */",
b"/** @brief d */",
b"/** @ingroup g */",
b"/** @internal d */",
b"/** @copyright d */",
b"/** @File */",
b"/** @class */",
b"/** @fn\n * d */",
b"/** @struct */",
b"/** \\\\file x */",
b"/** @@file x */",
b"/** a@file.com */",
b"/** `@file` */",
b"/**\n * ```\n * @file\n * ```\n */",
b"/**\n * @code\n * @file\n * @endcode\n */",
b"/**\n * @verbatim\n * @file\n * @endverbatim\n */",
b"/** @filex */",
b"/** `a\n * @file x\n * b` */",
b"/** `\n * @file x\n * b` */",
b"/** a@file-x.com */",
b"/** @file_x */",
b"/**\n * @verbatim\n * @endcode @file\n * @endverbatim\n */",
b"/**\n * @htmlonly @file @endhtmlonly\n */",
b"/**\n * @htmlonly[block] @file @endhtmlonly\n */",
b"/**\n * @htmlonly\n * @endlatexonly @file\n * @endhtmlonly\n */",
b"/**\n * @latexonly\n * @file\n */",
b"/** @xmlonly @file @endxmlonly */",
b"/** @rtfonly @file @endrtfonly */",
b"/** @manonly @file @endmanonly */",
b"/** @docbookonly @file @enddocbookonly */",
b"/** @dot @file @enddot */",
b"/** @msc @file @endmsc */",
b"/** @startuml @file @enduml */",
b"/** @icode @file @endicode */",
b"/** @iverbatim @file @endiverbatim */",
b"/** @iliteral @file @endiliteral */",
b"/**\n * <!-- @file -->\n */",
b"/**\n * <!-- x --->\n * @file\n */",
b"/**\n * <!-- x --!>\n * @file\n */",
b"/**\n * <!-- x\n * @file\n */",
b"/** \"@file\" */",
b"/** a \"b\" \"@file\" c */",
b"/** \"@file x\" \"@class X\" */",
b"/** <![CDATA[ @file ]]> */",
b"/** <![CDATA[ @file */",
b"/**\n * <![CDATA[\n * @file\n * ]]>\n */",
];
#[test]
fn doxygen_standalone_follows_commentscan() {
crate::test_support::assert_classifies(doxygen_standalone, STANDALONE, ATTACHED);
}
#[cfg(feature = "c")]
#[test]
fn conditional_declares_reads_each_conditional_once_per_walk() {
use crate::node::{FoldCache, Tree};
const DEPTH: usize = 40;
for (bottom, declares) in [("int x;\n", true), ("#include <x.h>\n", false)] {
let source = format!(
"{}{bottom}{}",
"/** d */\n#ifdef A\n".repeat(DEPTH),
"#endif\n".repeat(DEPTH)
);
let tree = Tree::new::<crate::langs::CCode>(source.as_bytes());
let nest: Vec<_> = tree
.get_root()
.preorder()
.filter(|node| preproc_conditional::<crate::langs::CCode>(node))
.collect();
assert_eq!(nest.len(), DEPTH, "{bottom}");
let cache = FoldCache::default();
let walk = Ancestors::known(&[]).with_folds(&cache);
let before = conditionals_read::observed();
for level in &nest {
assert_eq!(
conditional_declares::<crate::langs::CCode>(level, walk),
declares,
"{bottom}"
);
}
let memoised = conditionals_read::observed() - before;
let before = conditionals_read::observed();
for level in &nest {
assert_eq!(
conditional_declares::<crate::langs::CCode>(level, Ancestors::known(&[])),
declares,
"{bottom}"
);
}
let unmemoised = conditionals_read::observed() - before;
assert_eq!(memoised, DEPTH, "{bottom}");
if !declares {
assert_eq!(unmemoised, DEPTH * (DEPTH + 1) / 2, "{bottom}");
}
}
}
#[cfg(feature = "c")]
#[test]
fn conditional_declares_folds_in_every_child() {
use crate::langs::CCode;
use crate::node::{FoldCache, Tree};
let shapes: &[(&str, &[bool])] = &[
(
"#ifdef A\nint x;\n#ifdef B\n#endif\n#endif\n",
&[true, false],
),
(
"#ifdef A\n#ifdef B\n#endif\nint x;\n#endif\n",
&[true, false],
),
(
"#ifdef A\n#ifdef B\nint x;\n#endif\n#include <y.h>\n#endif\n",
&[true, true],
),
(
"#if A\n#ifdef B\n#endif\n#elif C\nint x;\n#else\n#ifdef D\n#endif\n#endif\n",
&[true, false, true, false, false],
),
];
for &(shape, answers) in shapes {
let tree = Tree::new::<CCode>(shape.as_bytes());
let nest: Vec<_> = tree
.get_root()
.preorder()
.filter(|node| preproc_conditional::<CCode>(node))
.zip(answers.iter().copied())
.collect();
assert_eq!(nest.len(), answers.len(), "{shape}");
for order in [nest.clone(), nest.iter().rev().copied().collect()] {
let cache = FoldCache::default();
let walk = Ancestors::known(&[]).with_folds(&cache);
for (level, declares) in &order {
let row = level.start_row();
let answer = conditional_declares::<CCode>(level, walk);
assert_eq!(answer, *declares, "{shape}: row {row}");
let answer = conditional_declares::<CCode>(level, Ancestors::known(&[]));
assert_eq!(answer, *declares, "{shape}: row {row}, unmemoised");
}
}
}
}
#[cfg(feature = "c")]
#[test]
fn doxygen_entry_never_reenters_the_conditional_walk() {
use crate::node::Tree;
const DEPTH: usize = 12;
for (bottom, declares) in [("int x;\n", true), ("#include <x.h>\n", false)] {
let source = format!(
"{}{bottom}{}",
"#ifdef A\n".repeat(DEPTH),
"#endif\n".repeat(DEPTH)
);
let tree = Tree::new::<crate::langs::CCode>(source.as_bytes());
let outermost = tree
.get_root()
.preorder()
.find(|node| preproc_conditional::<crate::langs::CCode>(node))
.expect("a nest");
for uncached in [Ancestors::known(&[]), Ancestors::unknown()] {
let before = conditionals_read::observed();
assert!(!doxygen_entry::<crate::langs::CCode>(&outermost, uncached));
assert_eq!(
conditionals_read::observed() - before,
0,
"{bottom}: an entry question reads no nest"
);
let before = conditionals_read::observed();
assert_eq!(
conditional_declares::<crate::langs::CCode>(&outermost, uncached),
declares,
"{bottom}"
);
assert_eq!(
conditionals_read::observed() - before,
DEPTH,
"{bottom}: one walk, each level once"
);
}
}
}
#[cfg(feature = "c")]
#[test]
fn error_child_is_asked_with_the_error_as_its_parent() {
use crate::node::Tree;
use std::cell::Cell;
thread_local! { static ASKED: Cell<usize> = const { Cell::new(0) }; }
struct ParentChecked;
impl DoxygenRow for ParentChecked {
fn doc_target_row<'a>(node: &Node<'a>, _: &[u8], ancestors: Ancestors<'a, '_>) -> bool {
assert_eq!(
ancestors.parent(node).map(|p| p.id()),
node.parent().map(|p| p.id()),
"{} asked with a chain not its own",
node.kind()
);
ASKED.with(|asked| asked.set(asked.get() + 1));
false
}
fn conditional_kind(kind: u16) -> bool {
<crate::langs::CCode as DoxygenRow>::conditional_kind(kind)
}
}
let source = b"int ok;\nQ_OBJECT\nint after;\n";
let tree = Tree::new::<crate::langs::CCode>(source);
let root = tree.get_root();
let mut chain = vec![root];
let mut stack: Vec<(Node, usize)> = root.children().map(|c| (c, 1)).collect();
let mut errors = 0;
while let Some((node, depth)) = stack.pop() {
chain.truncate(depth);
if node.is_error() {
errors += 1;
assert!(no_entry_inside::<ParentChecked>(
&node,
Ancestors::known(&chain)
));
}
chain.push(node);
stack.extend(node.children().map(|c| (c, depth + 1)));
}
assert_eq!(errors, 1, "one recovery error in the fixture");
assert_eq!(ASKED.with(Cell::get), 1, "the sole child was asked once");
}
#[test]
fn doxygen_member_after_takes_the_four_markers() {
for after in [&b"/**< d */"[..], b"/*!< d */", b"///< d", b"//!< d"] {
assert!(doxygen_member_after(after));
}
for before in [&b"/** d */"[..], b"/// d", b"//! d", b"/*! d */"] {
assert!(!doxygen_member_after(before));
}
}
}