use cpp_parser::{
CppParser, CppSyntaxKind, CppSyntaxTree, DocCommandKind, ParserConfig, command_kind,
};
fn parse(source: &str) -> CppSyntaxTree {
CppParser::parse(source, ParserConfig::default())
}
fn comments(tree: &CppSyntaxTree) -> Vec<cpp_parser::CppSyntaxNode> {
tree.get_red_root()
.descendants()
.filter(|node| CppSyntaxKind::from(node.kind()) == CppSyntaxKind::DocComment)
.collect()
}
fn subtree_text(node: &cpp_parser::CppSyntaxNode) -> String {
node.text().to_string()
}
fn command_names(node: &cpp_parser::CppSyntaxNode) -> Vec<String> {
node.descendants()
.filter(|child| CppSyntaxKind::from(child.kind()) == CppSyntaxKind::DocCommand)
.filter_map(|command| {
command
.children_with_tokens()
.filter_map(|element| element.into_token())
.find(|token| token.kind() == cpp_parser::CppTokenKind::DocCommandName.into())
.map(|token| token.text().to_string())
})
.collect()
}
fn argument_of(node: &cpp_parser::CppSyntaxNode, command: &str) -> Option<String> {
node.descendants()
.filter(|child| CppSyntaxKind::from(child.kind()) == CppSyntaxKind::DocCommand)
.find(|child| {
child
.children_with_tokens()
.filter_map(|element| element.into_token())
.any(|token| token.text() == command)
})
.and_then(|child| {
child
.children()
.filter(|grandchild| {
CppSyntaxKind::from(grandchild.kind()) == CppSyntaxKind::DocCommandArg
})
.last()
.map(|arg| subtree_text(&arg))
})
}
const LOSS_CORPUS: &[&str] = &[
"/// doc\nint x;\n",
"// plain\nint x;\n",
"/** block */\nint x;\n",
"/// a\n/// b\n/// c\nint x;\n",
"int /* inline */ x;\n",
"int x; /// trailing\n",
"/// @param x\nint f(int x);\n",
"/// @code\n/// int y = 1;\n/// @endcode\nint x;\n",
"/**\n * @brief x\n * @param[in] a\n */\nint f(int a);\n",
"/// tail without newline",
"///",
"/**/",
"//// banner\nint x;\n",
"/// emoji \u{1F600} and \u{4e2d}\u{6587}\nint x;\n",
"/* unterminated\nint x;\n",
];
#[test]
fn comments_are_lossless() {
for source in LOSS_CORPUS {
let tree = parse(source);
assert_eq!(
tree.to_source_text(),
*source,
"{source:?} did not round-trip: {:#?}",
tree.get_red_root()
);
}
}
#[test]
fn well_formed_comments_parse_cleanly() {
for source in LOSS_CORPUS {
if source.contains("unterminated") {
continue;
}
let tree = parse(source);
assert!(
tree.get_errors().is_empty(),
"{source:?} should parse cleanly, got {:?}",
tree.get_errors()
);
}
}
#[test]
fn a_comment_node_covers_exactly_its_comment() {
let source = "int x;\n/// doc\n/// more\nint y;\n";
let tree = parse(source);
let comment = comments(&tree).first().cloned().expect("a comment");
assert_eq!(
subtree_text(&comment),
"/// doc\n/// more",
"the comment node must cover both lines and nothing else"
);
}
#[test]
fn adjacent_line_comments_form_one_comment() {
let source = "/// one\n/// two\n/// three\nint x;\n";
let tree = parse(source);
let found = comments(&tree);
assert_eq!(found.len(), 1, "expected one group, got {}", found.len());
assert_eq!(subtree_text(&found[0]), "/// one\n/// two\n/// three");
}
#[test]
fn a_blank_line_ends_a_comment_group() {
let source = "/// file header\n\n/// documents x\nint x;\n";
let tree = parse(source);
let found = comments(&tree);
assert_eq!(
found.len(),
2,
"a blank line should end the group: {:#?}",
tree.get_red_root()
);
assert_eq!(subtree_text(&found[0]), "/// file header");
assert_eq!(subtree_text(&found[1]), "/// documents x");
}
#[test]
fn comments_on_one_line_are_one_group() {
let source = "/* a */ /* b */\nint x;\n";
let tree = parse(source);
assert_eq!(comments(&tree).len(), 1, "{:#?}", tree.get_red_root());
}
#[test]
fn a_plain_comment_is_not_parsed_for_commands() {
let source = "// @param x not documentation\nint f(int x);\n";
let tree = parse(source);
let comment = comments(&tree).first().cloned().expect("a comment");
assert!(
command_names(&comment).is_empty(),
"an ordinary `//` comment must not yield commands: {:#?}",
comment
);
assert_eq!(subtree_text(&comment), "// @param x not documentation");
}
#[test]
fn a_banner_is_not_documentation() {
let source = "//// section\n/// @param x real\nint f(int x);\n";
let tree = parse(source);
let found = comments(&tree);
let with_commands: Vec<&cpp_parser::CppSyntaxNode> = found
.iter()
.filter(|node| !command_names(node).is_empty())
.collect();
assert_eq!(
with_commands.len(),
1,
"only the `///` line documents: {found:#?}"
);
assert_eq!(command_names(with_commands[0]), vec!["param"]);
}
#[test]
fn commands_are_parsed_with_their_arguments() {
let source = "/// @param[in] x the x\n/// @param[out] y the y\nint f(int x, int* y);\n";
let tree = parse(source);
let comment = comments(&tree).first().cloned().expect("a comment");
assert_eq!(command_names(&comment), vec!["param", "param"]);
assert_eq!(
argument_of(&comment, "param"),
Some("x".to_string()),
"the argument is the name, not the name plus its description"
);
}
#[test]
fn a_backslash_command_is_the_same_as_an_at_command() {
let source = "/// \\brief Brief.\nint x;\n";
let tree = parse(source);
let comment = comments(&tree).first().cloned().expect("a comment");
assert_eq!(command_names(&comment), vec!["brief"]);
}
#[test]
fn command_names_are_case_insensitive() {
assert_eq!(command_kind("param"), Some(DocCommandKind::Parameter));
assert_eq!(command_kind("PARAM"), Some(DocCommandKind::Parameter));
assert_eq!(command_kind("Param"), Some(DocCommandKind::Parameter));
assert_eq!(command_kind("tparam"), Some(DocCommandKind::Parameter));
assert_eq!(command_kind("returns"), Some(DocCommandKind::Description));
assert_eq!(command_kind("throws"), Some(DocCommandKind::Exception));
assert_eq!(command_kind("see"), Some(DocCommandKind::Reference));
assert_eq!(command_kind("warning"), Some(DocCommandKind::Advisory));
assert_eq!(command_kind("todo"), Some(DocCommandKind::Callout));
}
#[test]
fn an_unknown_command_is_still_a_command() {
let source = "/// @myalias some text\nint x;\n";
let tree = parse(source);
assert!(
tree.get_errors().is_empty(),
"an alias must not be reported as broken: {:?}",
tree.get_errors()
);
let comment = comments(&tree).first().cloned().expect("a comment");
assert_eq!(command_names(&comment), vec!["myalias"]);
assert!(
subtree_text(&comment).contains("some text"),
"an unknown command's line must be kept"
);
assert_eq!(command_kind("myalias"), None);
}
#[test]
fn leading_text_is_the_description() {
let source = "/// Computes the area.\n/// @param r the radius.\ndouble area(double r);\n";
let tree = parse(source);
let comment = comments(&tree).first().cloned().expect("a comment");
assert_eq!(command_names(&comment), vec!["param"]);
assert!(
subtree_text(&comment).contains("Computes the area."),
"the leading text must be kept: {:#?}",
comment
);
}
#[test]
fn a_block_comment_body_continues_across_lines() {
let source = "/**\n * @brief First line\n * second line\n */\nint x;\n";
let tree = parse(source);
let comment = comments(&tree).first().cloned().expect("a comment");
let body = comment
.descendants()
.find(|node| CppSyntaxKind::from(node.kind()) == CppSyntaxKind::DocCommandBody)
.expect("a command body");
assert!(
subtree_text(&body).contains("second line"),
"the block comment's second line belongs to the brief: {:#?}",
body
);
}
#[test]
fn a_code_block_is_not_parsed_as_documentation() {
let source = "/// @code\n/// std::vector<int> v; // @notacommand\n/// @endcode\n/// @param x real\nint f(int x);\n";
let tree = parse(source);
let comment = comments(&tree).first().cloned().expect("a comment");
assert_eq!(
command_names(&comment),
vec!["code", "param"],
"only the real commands should be found: {:#?}",
comment
);
let code = comment
.descendants()
.find(|node| CppSyntaxKind::from(node.kind()) == CppSyntaxKind::DocCodeBlock)
.expect("a code block");
assert!(
subtree_text(&code).contains("std::vector<int>"),
"the snippet must be kept verbatim: {:#?}",
code
);
}
#[test]
fn a_comment_does_not_swallow_the_declaration() {
let source = "/// doc\n/// @param x the x\nint f(int x);\nint g;\n";
let tree = parse(source);
let root = tree.get_red_root();
let comment = comments(&tree).first().cloned().expect("a comment");
let comment_end = u32::from(comment.text_range().end());
let declaration_start = source.find("int f").expect("the declaration") as u32;
assert_eq!(
comment_end,
declaration_start - 1,
"the comment ends after the newline that follows it, and no later: {:#?}",
root
);
let declarations: Vec<_> = root
.children()
.filter(|node| CppSyntaxKind::from(node.kind()) == CppSyntaxKind::Declaration)
.collect();
assert_eq!(
declarations.len(),
2,
"both declarations must be top-level: {:#?}",
root
);
}
#[test]
fn the_event_stream_stays_balanced_with_comments() {
for source in LOSS_CORPUS {
let (_, audit) = CppParser::parse_with_audit(source, ParserConfig::default());
assert!(
audit.is_balanced(),
"{source:?} left the event stream unbalanced: {audit:?}"
);
}
}
#[test]
fn a_comment_without_a_declaration_is_fine() {
let cases = [
"/// just a comment",
"/// just a comment\n",
"/// @param x nothing to document",
"/** @brief nothing follows */",
"// plain\n",
];
for source in cases {
let tree = parse(source);
assert_eq!(tree.to_source_text(), *source, "{source:?} lost text");
assert!(
tree.get_errors().is_empty(),
"{source:?} should parse cleanly: {:?}",
tree.get_errors()
);
assert_eq!(comments(&tree).len(), 1, "{source:?}");
}
}
#[test]
fn comments_attach_where_they_are_found() {
let source = "class C {\npublic:\n /// documents m\n int m;\n};\n";
let tree = parse(source);
let comment = comments(&tree).first().cloned().expect("a comment");
let parent = comment.parent().expect("a parent");
assert_eq!(
CppSyntaxKind::from(parent.kind()),
CppSyntaxKind::ClassBody,
"the comment belongs to the class body: {:#?}",
tree.get_red_root()
);
}
#[test]
fn a_trailing_comment_is_kept() {
let source = "int x; ///< the x\nint y;\n";
let tree = parse(source);
assert_eq!(tree.to_source_text(), source);
assert_eq!(comments(&tree).len(), 1);
}
#[test]
fn half_typed_comments_do_not_break_anything() {
let cases = [
"/// @",
"/// @param",
"/// @param[",
"/// @param[in",
"/// @code",
"/// @code\n/// int x =",
"/** @brief",
"/**\n *",
"/// \\",
"/// @@@@",
"/// @ref",
"/// @param x =",
"///",
"/// @endcode",
];
for source in cases {
let tree = parse(source);
assert_eq!(
tree.to_source_text(),
source,
"{source:?} lost text: {:#?}",
tree.get_red_root()
);
if !source.starts_with("/*") || source.contains("*/") {
assert!(
tree.get_errors().is_empty(),
"{source:?} is a comment, not an error: {:?}",
tree.get_errors()
);
}
let (_, audit) = CppParser::parse_with_audit(source, ParserConfig::default());
assert!(audit.is_balanced(), "{source:?}: {audit:?}");
}
}
#[test]
fn comments_between_tokens_do_not_disturb_the_cpp_grammar() {
let cases = [
"int /* c */ x;\n",
"int x /* c */ ;\n",
"void f(/* c */ int a);\n",
"struct S { /// doc\n int m; };\n",
"int a; /// doc\n/// more\nint b;\n",
"namespace n { /// doc\nint x; }\n",
"#include <vector> /// doc\nint x;\n",
];
for source in cases {
let tree = parse(source);
assert_eq!(tree.to_source_text(), *source, "{source:?} lost text");
assert!(
tree.get_errors().is_empty(),
"{source:?} should parse cleanly: {:?}",
tree.get_errors()
);
}
}
#[test]
fn a_realistic_module_unit_yields_its_documentation() {
let source = include_str!("real_world.cpp");
let tree = parse(source);
assert_eq!(
tree.get_errors(),
[],
"documentation must not turn valid code into a diagnostic: {:?}",
tree.get_errors()
);
assert_eq!(
tree.to_source_text(),
source,
"the tree must reproduce the file"
);
let found = comments(&tree);
assert!(
found.len() >= 8,
"expected a documentation block per documented entity, found {}: {:#?}",
found.len(),
tree.get_red_root()
);
let mut commands: Vec<(String, Vec<String>)> = Vec::new();
for comment in &found {
for command in comment
.descendants()
.filter(|node| CppSyntaxKind::from(node.kind()) == CppSyntaxKind::DocCommand)
{
let name = command
.children_with_tokens()
.filter_map(|element| element.into_token())
.find(|token| token.kind() == cpp_parser::CppTokenKind::DocCommandName.into())
.map(|token| token.text().to_string())
.unwrap_or_default();
let args: Vec<String> = command
.children()
.filter(|node| CppSyntaxKind::from(node.kind()) == CppSyntaxKind::DocCommandArg)
.map(|arg| subtree_text(&arg))
.collect();
commands.push((name, args));
}
}
assert!(
commands.contains(&("param".to_string(), vec!["x".to_string()])),
"the constructor's parameters must be documented by name: {commands:?}"
);
assert!(
commands.contains(&("param".to_string(), vec!["y".to_string()])),
"{commands:?}"
);
assert!(
commands.contains(&("tparam".to_string(), vec!["T".to_string()])),
"template parameters need their own command: {commands:?}"
);
for name in [
"file", "brief", "returns", "note", "warning", "code", "copydoc",
] {
assert!(
commands.iter().any(|(command, _)| command == name),
"`@{name}` should have been recognised: {commands:?}"
);
}
let block = found
.iter()
.flat_map(|comment| comment.descendants())
.find(|node| CppSyntaxKind::from(node.kind()) == CppSyntaxKind::DocCodeBlock)
.expect("a code block");
let block_text = subtree_text(&block);
assert!(
block_text.contains("Grid<double, 4> g;"),
"the first line of the snippet must be inside the block: {block_text:?}"
);
assert!(
block_text.contains("g.at(0) = 1.0;"),
"so must the second — a block that ends at the first `///` line is the bug this covers: \
{block_text:?}"
);
assert!(
block_text.trim_end().ends_with("@endcode"),
"the block ends at `@endcode`: {block_text:?}"
);
assert!(
commands
.iter()
.any(|(name, args)| name == "brief" && args.is_empty()),
"{commands:?}"
);
}
#[test]
fn a_doc_comment_names_the_symbols_it_refers_to() {
let text = "\
/// See [`Widget::grow`] and [`std::vector`].
/// The index `arr[i]` is not a link, and neither is `matrix[row][col]`.
/// A title [`a b`] is prose.
void f() {}
";
let links = cpp_parser::doc_links(text, cpp_parser::SourceRange::new(0, text.len()));
let targets: Vec<&str> = links.iter().map(|link| link.target.as_str()).collect();
assert_eq!(targets, vec!["Widget::grow", "std::vector"], "{links:?}");
for link in &links {
assert_eq!(
&text[link.range.start_offset..link.range.end_offset()],
link.target,
"the range is the target itself, not the brackets around it"
);
}
}
#[test]
fn a_reference_command_names_the_symbol_after_it() {
let text = "\
/// @see Widget::grow
/// @sa std::vector<int>, and see below.
/// @param x is a parameter, not a reference.
/// @ref widget.h for the header.
";
let references = cpp_parser::doc_references(text, cpp_parser::SourceRange::new(0, text.len()));
let targets: Vec<&str> = references.iter().map(|one| one.target.as_str()).collect();
assert_eq!(
targets,
vec!["Widget::grow", "std::vector<int>", "widget.h"],
"{references:?}"
);
for reference in &references {
assert_eq!(
&text[reference.range.start_offset..reference.range.end_offset()],
reference.target,
"the range is the target itself"
);
}
}