use cpp_code_analysis::file::view::{documentation_at, might_be_documented};
use cpp_code_analysis::{
CompilerConfig, MemoryFiles, OpenDocuments, Session, SessionFiles, WatchFilter,
};
fn session_with(files: &[(&str, &str)]) -> Session<MemoryFiles> {
let mut memory = MemoryFiles::new();
for (path, source) in files {
memory = memory.with_file(*path, *source);
}
let providers = SessionFiles::new(OpenDocuments::new(), memory);
let mut session = Session::with_config(
"/p",
providers,
WatchFilter::new("/p"),
CompilerConfig::default(),
);
for (path, _) in files {
session.load(path);
}
session
}
fn documentation_in(source: &str, offset: usize) -> Option<String> {
let mut session = session_with(&[("/p/a.cpp", source)]);
session.want_cooked_reading(std::path::Path::new("/p/a.cpp"));
session.index_everything();
let view = session.view("/p/a.cpp").expect("the file is held");
session
.documentation(&view, std::path::Path::new("/p/a.cpp"), offset)
.map(|comment| comment.get_comment_text())
}
#[test]
fn a_declaration_reports_the_comment_above_it() {
let source = "/// Doc.\nint x;\n";
assert_eq!(
documentation_in(source, source.find("int x").expect("the fixture")),
Some("Doc.".to_string())
);
}
#[test]
fn every_offset_of_the_declaration_reports_it() {
let source = "/// Doc.\nint f(Widget& w);\n";
let start = source.find("int f").expect("the fixture");
let end = source.find(';').expect("the fixture");
for offset in start..=end {
assert_eq!(
documentation_in(source, offset),
Some("Doc.".to_string()),
"the declaration is documented at offset {offset}"
);
}
}
#[test]
fn a_member_is_not_documented_by_the_class_comment() {
let source = "/// The class.\nstruct S {\n /// The n.\n int n;\n};\n";
assert_eq!(
documentation_in(source, source.find("struct S").expect("the fixture")),
Some("The class.".to_string())
);
assert_eq!(
documentation_in(source, source.find("int n").expect("the fixture")),
Some("The n.".to_string())
);
}
#[test]
fn a_member_documented_by_a_nested_comment_is_found_too() {
let source = "struct S {\n int x;\n /// The y.\n int y;\n};\n";
assert_eq!(
documentation_in(source, source.find("int y").expect("the fixture")),
Some("The y.".to_string())
);
assert_eq!(
documentation_in(source, source.find("int x").expect("the fixture")),
None,
"the comment below `x` is not `x`'s documentation"
);
}
#[test]
fn a_trailing_comment_documents_nothing_at_the_cursor() {
let source = "struct S {\n int a; ///< the a\n int b;\n};\n";
assert_eq!(
documentation_in(source, source.find("int b").expect("the fixture")),
None
);
}
#[test]
fn a_plain_comment_is_found_but_is_not_documentation() {
let source = "// A note.\nint x;\n";
let mut session = session_with(&[("/p/a.cpp", source)]);
session.want_cooked_reading(std::path::Path::new("/p/a.cpp"));
session.index_everything();
let view = session.view("/p/a.cpp").expect("the file is held");
let found = session
.documentation(
&view,
std::path::Path::new("/p/a.cpp"),
source.find("int x").expect("the fixture"),
)
.expect("the comment documents the declaration");
assert_eq!(found.get_comment_text(), "A note.");
assert!(
!found.is_documentation(),
"`//` is not one of the spellings the lexer calls documentation"
);
}
#[test]
fn a_declaration_with_nothing_above_it_has_no_documentation() {
assert_eq!(documentation_in("int x;\n", 0), None);
assert_eq!(documentation_in("int x;\nint y;\n", 7), None);
}
#[test]
fn the_declaring_file_answers_too() {
let header = "/// A widget.\nstruct Widget {\n int size;\n};\n";
let source = "#include \"b.h\"\nint f(Widget& w) { return w.size; }\n";
let mut session = session_with(&[("/p/a.cpp", source), ("/p/b.h", header)]);
session.want_cooked_reading(std::path::Path::new("/p/a.cpp"));
session.index_everything();
let view = session.view("/p/a.cpp").expect("the file is held");
let found = session
.documentation(
&view,
std::path::Path::new("/p/b.h"),
header.find("struct Widget").expect("the fixture"),
)
.expect("the header documents the class");
assert_eq!(found.get_comment_text(), "A widget.");
}
#[test]
fn an_unreadable_file_has_no_documentation() {
let mut session = session_with(&[("/p/a.cpp", "int x;\n")]);
session.want_cooked_reading(std::path::Path::new("/p/a.cpp"));
session.index_everything();
let view = session.view("/p/a.cpp").expect("the file is held");
assert!(
session
.documentation(&view, std::path::Path::new("/p/missing.h"), 0)
.is_none()
);
}
#[test]
fn the_check_never_rejects_a_comment_the_parser_finds() {
let cases = [
("/// Doc.\nint x;\n", "int x"),
("//! Doc.\nint x;\n", "int x"),
("/** Doc. */\nint x;\n", "int x"),
("/** Doc. */ int x;\n", "int x"),
("/* Doc.\n More. */\nint x;\n", "int x"),
("/// Doc.\n#define N 3\nint x;\n", "int x"),
("/// Doc.\n#define N 3\n\n#define M 4\nint x;\n", "int x"),
(
"struct S {\n int a;\n /// Doc.\n int b;\n};\n",
"int b",
),
("namespace ns {\n/// Doc.\nint x;\n}\n", "int x"),
];
for (source, declaration) in cases {
let offset = source.find(declaration).expect("the fixture declares it");
let tree = cpp_parser::CppParser::parse(source, cpp_parser::ParserConfig::default());
let found = documentation_at(&tree.get_red_root(), offset);
assert!(
found.is_some(),
"{source:?} documents `{declaration}` and the parser has to find it"
);
assert!(
might_be_documented(source, offset),
"{source:?} would be skipped by the check before the parse that finds its comment"
);
}
}
#[test]
fn a_declaration_with_code_above_it_is_not_worth_a_parse() {
let source = "int a;\nint b;\n";
assert!(!might_be_documented(
source,
source.find("int b").expect("the fixture")
));
let source = "struct S {\n int a;\n int b;\n};\n";
assert!(!might_be_documented(
source,
source.find("int b").expect("the fixture")
));
assert!(!might_be_documented("int x;\n", 0));
}
#[test]
fn a_directive_above_a_declaration_does_not_hide_a_comment() {
let source = "/// Doc.\n#define N 3\nint x;\n";
assert!(might_be_documented(
source,
source.find("int x").expect("the fixture")
));
}
#[test]
fn a_comment_above_a_multi_line_head_is_found() {
let text = "\
_GLIBCXX_BEGIN_NAMESPACE_VERSION
/**
* @brief Write a newline and flush the stream.
*
* This manipulator is often mistakenly used when a simple newline is desired.
*/
template<typename _CharT, typename _Traits>
inline basic_ostream<_CharT, _Traits>&
endl(basic_ostream<_CharT, _Traits>& __os)
{ return flush(__os.put(__os.widen('\n'))); }
int size;
";
let at = text.find("endl(basic_ostream").expect("the fixture");
assert!(
might_be_documented(text, at),
"the comment sits above the template head, and the check has to walk over it"
);
assert_eq!(
documentation_at(
&cpp_parser::CppParser::parse(text, cpp_parser::ParserConfig::default()).get_red_root(),
at
)
.map(|comment| comment.get_comment_text().to_string()),
Some(" @brief Write a newline and flush the stream.\n\n This manipulator is often mistakenly used when a simple newline is desired.".to_string()),
"and the comment the parser finds is that one"
);
}