use cpp_parser::{CppKind, CppParser, CppSyntaxKind, CppSyntaxTree, CppTokenKind, ParserConfig};
fn parse(source: &str) -> CppSyntaxTree {
CppParser::parse(source, ParserConfig::default())
}
fn render(node: &cpp_parser::CppSyntaxNode, out: &mut String) {
for child in node.children() {
let kind = format!("{:?}", CppSyntaxKind::from(child.kind()));
let tokens = direct_tokens(&child);
out.push_str(&format!("{kind}[{tokens}]"));
let has_children = child.children().next().is_some();
if has_children {
out.push('(');
render(&child, out);
out.push(')');
}
out.push(' ');
}
while out.ends_with(' ') {
out.pop();
}
}
fn doc_shape(source: &str) -> String {
let tree = parse(source);
assert_eq!(
tree.get_errors(),
[],
"the input must parse cleanly for its shape to mean anything: {:?}",
tree.get_errors()
);
assert_eq!(
tree.to_source_text(),
source,
"the shape must be of a tree that still reproduces the file"
);
let comment = tree
.get_red_root()
.descendants()
.find(|node| CppSyntaxKind::from(node.kind()) == CppSyntaxKind::DocComment)
.expect("a documentation comment");
let kind = format!("{:?}", CppSyntaxKind::from(comment.kind()));
let mut inner = String::new();
render(&comment, &mut inner);
format!("{kind}({inner})")
}
fn direct_tokens(node: &cpp_parser::CppSyntaxNode) -> String {
let raw: String = node
.children_with_tokens()
.filter_map(|element| element.into_token())
.filter(|token| {
!matches!(
token.kind(),
CppKind::Token(CppTokenKind::Whitespace) | CppKind::Token(CppTokenKind::Newline)
)
})
.map(|token| token.text().to_string())
.collect();
let mut out = String::with_capacity(raw.len());
for word in raw.split_whitespace() {
if !out.is_empty() && !out.ends_with(['/', '@']) {
out.push(' ');
}
out.push_str(word);
}
out
}
fn doc_content_shape(source: &str) -> String {
let tree = parse(source);
assert_eq!(tree.to_source_text(), source);
let body = tree
.get_red_root()
.descendants()
.find(|node| CppSyntaxKind::from(node.kind()) == CppSyntaxKind::DocCommentBody)
.expect("a comment body");
let mut inner = String::new();
render(&body, &mut inner);
inner
}
#[test]
fn one_comment_is_one_body_of_commands() {
assert_eq!(
doc_shape("/// @param x the x\nint f(int x);\n"),
"DocComment(DocCommentBody[///@](DocCommand[param](DocCommandArg[x] \
DocCommandBody[the x])))"
);
}
#[test]
fn several_lines_are_one_body() {
assert_eq!(
doc_shape("/// @brief B\n/// @param x the x\n/// @returns R\nint f(int x);\n"),
"DocComment(DocCommentBody[///@///@///@](DocCommand[brief](DocCommandBody[B]) \
DocCommand[param](DocCommandArg[x] DocCommandBody[the x]) \
DocCommand[returns](DocCommandBody[R])))"
);
}
#[test]
fn line_and_block_spellings_agree() {
let line = doc_content_shape("/// @brief B\n/// @param x the x\nint f(int x);\n");
let block = doc_content_shape("/** @brief B\n * @param x the x\n */\nint f(int x);\n");
assert_eq!(
line, block,
"the two spellings of the same documentation must not differ in shape"
);
assert_eq!(
line,
"DocCommand[brief](DocCommandBody[B]) DocCommand[param](DocCommandArg[x] \
DocCommandBody[the x])"
);
}
#[test]
fn the_argument_and_its_description_are_separate() {
let one_space = doc_shape("/// @param x the x\nint f(int x);\n");
let two_spaces = doc_shape("/// @param x the x\nint f(int x);\n");
assert_eq!(one_space, two_spaces, "one space or two must not matter");
assert!(
one_space.contains("DocCommandArg[x] DocCommandBody[the x]"),
"the name and its description must be separate nodes: {one_space}"
);
}
#[test]
fn a_command_without_an_argument_has_no_argument_node() {
assert_eq!(
doc_shape("/// @brief B\nint x;\n"),
"DocComment(DocCommentBody[///@](DocCommand[brief](DocCommandBody[B])))"
);
assert_eq!(
doc_shape("/// @param\nint f(int x);\n"),
"DocComment(DocCommentBody[///@](DocCommand[param]))"
);
}
#[test]
fn a_direction_is_an_argument_before_the_name() {
assert_eq!(
doc_shape("/// @param[in] x the x\nint f(int x);\n"),
"DocComment(DocCommentBody[///@](DocCommand[param](DocCommandArg[[in]] DocCommandArg[x] \
DocCommandBody[the x])))"
);
}
#[test]
fn leading_prose_is_a_body_without_a_command() {
assert_eq!(
doc_shape("/// Some prose.\nint x;\n"),
"DocComment(DocCommentBody[///](DocCommandBody[Some prose.]))"
);
}
#[test]
fn a_reference_keeps_its_qualification() {
assert_eq!(
doc_shape("/// @ref ns::Foo<T>\nint x;\n"),
"DocComment(DocCommentBody[///@](DocCommand[ref](DocCommandArg[ns::Foo<T>])))"
);
}
#[test]
fn a_code_block_spans_its_comments() {
assert_eq!(
doc_shape("/// @code\n/// int y = 1;\n/// int z = 2;\n/// @endcode\nint x;\n"),
"DocComment(DocCommentBody[///@](DocCommand[code] \
DocCodeBlock[///int y = 1;///int z = 2;///@endcode]))"
);
}
#[test]
fn an_unterminated_code_block_is_still_one_node() {
assert_eq!(
doc_shape("/// @code\n/// int y = 1;\nint x;\n"),
"DocComment(DocCommentBody[///@](DocCommand[code] DocCodeBlock[///int y = 1;]))"
);
}
#[test]
fn a_closed_code_block_does_not_swallow_what_follows() {
assert_eq!(
doc_shape("/// @code\n/// int y = 1;\n/// @endcode\n/// @param x the x\nint f(int x);\n"),
"DocComment(DocCommentBody[///@///@](DocCommand[code] \
DocCodeBlock[///int y = 1;///@endcode] DocCommand[param](DocCommandArg[x] \
DocCommandBody[the x])))"
);
}
#[test]
fn a_plain_comment_has_no_commands() {
assert_eq!(
doc_shape("// plain\nint x;\n"),
"DocComment(DocCommentBody[//plain])"
);
let tree = parse("// @param x not documentation\nint x;\n");
let body = tree
.get_red_root()
.descendants()
.find(|node| CppSyntaxKind::from(node.kind()) == CppSyntaxKind::DocCommentBody)
.expect("a comment body");
assert!(
body.text()
.to_string()
.contains("@param x not documentation"),
"the whole comment is prose: {:?}",
body.text().to_string()
);
let plain = doc_shape("// @param x not documentation\nint x;\n");
assert!(
!plain.contains("DocCommand"),
"a plain comment has no commands: {plain}"
);
}
#[test]
fn a_banner_is_a_plain_comment() {
assert_eq!(
doc_shape("//// section\nint x;\n"),
"DocComment(DocCommentBody[////section])"
);
}
#[test]
fn an_empty_comment_keeps_its_shape() {
assert_eq!(
doc_shape("///\nint x;\n"),
"DocComment(DocCommentBody[///])"
);
assert_eq!(
doc_shape("/**/\nint x;\n"),
"DocComment(DocCommentBody[/**/])"
);
}
#[test]
fn a_block_comment_closer_is_outside_the_body() {
let shape = doc_shape("/** @brief B */\nint x;\n");
assert_eq!(
shape,
"DocComment(DocCommentBody[/**@*/](DocCommand[brief](DocCommandBody[B])))"
);
let tree = parse("/** @brief B */\nint x;\n");
let body = tree
.get_red_root()
.descendants()
.find(|node| CppSyntaxKind::from(node.kind()) == CppSyntaxKind::DocCommandBody)
.expect("a brief body");
let text = body.text().to_string();
assert_eq!(
text.trim(),
"B",
"the body is the brief's text and nothing else: {text:?}"
);
assert!(
!text.contains("*/"),
"the comment's terminator must not be inside the body: {text:?}"
);
}
#[test]
fn a_multiline_block_body_stops_at_the_closer() {
let tree = parse("/**\n * @brief First\n * second\n */\nint x;\n");
let body = tree
.get_red_root()
.descendants()
.find(|node| CppSyntaxKind::from(node.kind()) == CppSyntaxKind::DocCommandBody)
.expect("a brief body");
let text = body.text().to_string();
assert!(
text.contains("First") && text.contains("second"),
"the continuation lines belong to the brief: {text:?}"
);
assert!(
!text.contains("*/"),
"a body must not end with the comment's closer: {text:?}"
);
assert_eq!(
tree.to_source_text(),
"/**\n * @brief First\n * second\n */\nint x;\n"
);
}
#[test]
fn every_doc_tree_has_the_invariants_a_consumer_relies_on() {
let corpus = [
"///\nint x;\n",
"/// @\nint x;\n",
"/// @param\nint f(int x);\n",
"/// @param x\nint f(int x);\n",
"/// @param x the x\nint f(int x);\n",
"/// @param[in] x the x\nint f(int x);\n",
"/// @param[] x\nint f(int x);\n",
"/// @code\nint x;\n",
"/// @code\n/// y\n/// @endcode\nint x;\n",
"/// @endcode\nint x;\n",
"/// @code @endcode\nint x;\n",
"/** @brief B */\nint x;\n",
"/**\n * @brief B\n */\nint x;\n",
"/**\n@brief B\n*/\nint x;\n",
"/** */\nint x;\n",
"/**/\nint x;\n",
"// plain\nint x;\n",
"//// banner\nint x;\n",
"/// @ref a::b\n/// @note n\n/// @warning w\nint x;\n",
"/// @brief B\n\n/// @note N\nint x;\n",
"int x; ///< trailing\n",
"struct S { /// doc\n int m; };\n",
"/// @code\n",
"///",
"/**",
"/** @brief",
];
for source in corpus {
let tree = parse(source);
let root = tree.get_red_root();
assert_eq!(
tree.to_source_text(),
source,
"{source:?} was not reproduced by its tree"
);
let comments: Vec<_> = root
.descendants()
.filter(|node| CppSyntaxKind::from(node.kind()) == CppSyntaxKind::DocComment)
.collect();
for comment in &comments {
assert!(
!subtree_text_of(comment).is_empty(),
"{source:?}: a comment node covers no text at all"
);
}
for comment in &comments {
let bodies: Vec<_> = comment
.children()
.filter(|node| CppSyntaxKind::from(node.kind()) == CppSyntaxKind::DocCommentBody)
.collect();
assert!(
bodies.len() <= 1,
"{source:?}: {} bodies under one comment; a consumer iterating commands must not \
have to walk a body per line: {:#?}",
bodies.len(),
comment
);
if let Some(body) = bodies.first() {
for command in body
.descendants()
.filter(|node| CppSyntaxKind::from(node.kind()) == CppSyntaxKind::DocCommand)
{
assert!(
command.parent().is_some(),
"{source:?}: a command with no parent"
);
}
}
}
for argument in root
.descendants()
.filter(|node| CppSyntaxKind::from(node.kind()) == CppSyntaxKind::DocCommandArg)
{
let under_a_command = argument
.ancestors()
.any(|node| CppSyntaxKind::from(node.kind()) == CppSyntaxKind::DocCommand);
assert!(
under_a_command,
"{source:?}: an argument node outside any command: {:#?}",
argument
);
}
for block in root
.descendants()
.filter(|node| CppSyntaxKind::from(node.kind()) == CppSyntaxKind::DocCodeBlock)
{
let inside_a_comment = block
.ancestors()
.any(|node| CppSyntaxKind::from(node.kind()) == CppSyntaxKind::DocComment);
assert!(
inside_a_comment,
"{source:?}: a code block outside any comment"
);
}
for body in root
.descendants()
.filter(|node| CppSyntaxKind::from(node.kind()) == CppSyntaxKind::DocCommandBody)
{
let text = body.text().to_string();
let trimmed = text.trim_end_matches([' ', '\t', '*']);
assert_eq!(
trimmed, text,
"{source:?}: a body ends in the comment's layout, so a consumer rendering it prints \
that layout: {text:?}"
);
assert!(
!text.starts_with([' ', '\t']),
"{source:?}: a body starts with layout the command already implied: {text:?}"
);
assert!(
!text.contains("*/"),
"{source:?}: a body contains the comment's terminator: {text:?}"
);
}
}
}
#[test]
fn a_command_is_named_by_its_first_token() {
let tree = parse("/// @param x the x\nint f(int x);\n");
let command = tree
.get_red_root()
.descendants()
.find(|node| CppSyntaxKind::from(node.kind()) == CppSyntaxKind::DocCommand)
.expect("a command");
let name = command
.children_with_tokens()
.filter_map(|element| element.into_token())
.find(|token| token.kind() == CppKind::Token(CppTokenKind::DocCommandName))
.expect("a name token");
assert_eq!(name.text().to_string(), "param");
assert!(
command
.descendants()
.any(|node| { CppSyntaxKind::from(node.kind()) == CppSyntaxKind::DocCommandArg })
);
assert!(
command
.descendants()
.any(|node| { CppSyntaxKind::from(node.kind()) == CppSyntaxKind::DocCommandBody })
);
}
#[test]
fn a_description_never_includes_the_layout_around_it() {
let cases = [
("/// @brief B\nint x;\n", "B"),
("/// @brief B\nint x;\n", "B"),
("/** @brief B */\nint x;\n", "B"),
("/** @brief B */\nint x;\n", "B"),
("/** @brief B\n */\nint x;\n", "B"),
("/// @param x the x\nint f(int x);\n", "the x"),
("/// @param x the x\nint f(int x);\n", "the x"),
("/** @brief A\n * B */\nint x;\n", "A\n * B"),
];
for (source, expected) in cases {
let tree = parse(source);
let body = tree
.get_red_root()
.descendants()
.find(|node| CppSyntaxKind::from(node.kind()) == CppSyntaxKind::DocCommandBody)
.unwrap_or_else(|| panic!("{source:?} has a body"));
assert_eq!(
body.text().to_string(),
expected,
"{source:?}: the body is what the description says, and nothing around it"
);
}
}
fn subtree_text_of(node: &cpp_parser::CppSyntaxNode) -> String {
node.text().to_string()
}