cpp_parser 0.1.4

A lossless C++ parser over the preprocessed text: the tree every layer above it reads.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
//! What a documentation comment is *attached to*.
//!
//! The grammar emits a comment into whatever node was open when it was found, which makes it a
//! **sibling** of the declaration it documents rather than a child. That is the right shape for a
//! lossless tree — a comment between two members belongs to the class body, not to either member — but
//! it means the relationship has to be read forwards from the comment, and nothing in the tree says
//! which way that is. These tests are that contract.
//!
//! Two questions, deliberately separate:
//!
//! * [`CppDocComment::get_owner`] — "what follows?", which always has an answer when something does.
//! * [`CppDocComment::get_documented_declaration`] — "what does this document?", which is the narrower
//!   question a hover or a signature help asks and which has no answer for a comment that documents
//!   nothing.

use cpp_parser::{
    CppAstNode, CppDeclaration, CppDocComment, CppParser, CppSyntaxKind, CppSyntaxTree,
    ParserConfig, documentation_of,
};

fn parse(source: &str) -> CppSyntaxTree {
    CppParser::parse(source, ParserConfig::default())
}

/// Every documentation comment in the tree, outermost first.
fn comments(tree: &CppSyntaxTree) -> Vec<CppDocComment> {
    tree.get_red_root()
        .descendants()
        .filter_map(CppDocComment::cast)
        .collect()
}

/// The single comment in a one-comment source.
fn the_comment(source: &str) -> CppDocComment {
    let tree = parse(source);
    let mut found = comments(&tree);
    assert_eq!(
        found.len(),
        1,
        "{source:?} should hold exactly one comment: {:#?}",
        tree.get_red_root()
    );
    found.remove(0)
}

/// The name of the declaration a comment documents.
///
/// The accessor absorbs the shape differences between declaration forms — a `using` alias keeps its
/// name in a child node rather than in a declarator — so this is the whole query.
fn documented_name(comment: &CppDocComment) -> Option<String> {
    comment.get_documented_name()
}

// ============================================================================
// The forward relationship
// ============================================================================

#[test]
fn a_comment_documents_the_declaration_after_it() {
    assert_eq!(
        documented_name(&the_comment("/// Doc.\nint x;\n")),
        Some("x".to_string())
    );
}

/// The comment is a *sibling*, so `get_owner` answers with the next node and not with a parent.
///
/// This is the property the whole design rests on: if the comment had been made a child of its
/// declaration, the class-body case below would put it inside the wrong member.
#[test]
fn the_owner_is_the_next_node_not_the_parent() {
    let comment = the_comment("/// Doc.\nint x;\n");
    let owner = comment.get_owner().expect("a following node");
    assert_eq!(
        CppSyntaxKind::from(owner.kind()),
        CppSyntaxKind::Declaration
    );

    assert_eq!(
        comment
            .get_parent::<cpp_parser::CppTranslationUnit>()
            .map(|unit| unit.syntax().text().to_string()),
        Some("/// Doc.\nint x;\n".to_string()),
        "the parent is the translation unit, not the declaration"
    );
}

/// A class definition is a declaration too, and a comment in front of one documents the class.
#[test]
fn a_comment_documents_a_class_definition() {
    assert_eq!(
        documented_name(&the_comment("/// A grid.\nclass Grid {\n    int n;\n};\n")),
        Some("Grid".to_string())
    );
}

/// A function, an alias, a variable: the same relationship, whatever the declaration form.
#[test]
fn the_documented_declaration_is_found_for_every_form() {
    let cases = [
        ("/// Doc.\nint f();\n", "f"),
        ("/// Doc.\nint x = 1;\n", "x"),
        ("/// Doc.\nenum class Color { Red };\n", "Color"),
        ("/// Doc.\nvoid f() { }\n", "f"),
    ];

    for (source, expected) in cases {
        assert_eq!(
            documented_name(&the_comment(source)),
            Some(expected.to_string()),
            "{source:?}"
        );
    }
}

/// A `using` alias is its own node kind rather than a `Declaration`, because its shape is not
/// `specifiers declarators`. It still declares a name, so the relationship has to survive it.
#[test]
fn a_using_alias_is_documented_too() {
    assert_eq!(
        documented_name(&the_comment("/// Doc.\nusing Point = shapes::Point;\n")),
        Some("Point".to_string())
    );
}

// ============================================================================
// What a comment does *not* document
// ============================================================================

/// Nothing follows, so there is nothing to document — and `get_owner` says so rather than inventing
/// a relationship with the file.
#[test]
fn a_comment_at_the_end_of_a_file_documents_nothing() {
    let comment = the_comment("int x;\n/// Trailing note.\n");

    assert!(comment.get_owner().is_none(), "nothing follows the comment");
    assert!(comment.get_documented_declaration().is_none());
}

/// A trailing `///<` documents the member *before* it, which this forward-only relationship cannot
/// see. Reporting the following declaration instead would attach the comment to the wrong member, so
/// the answer is `None` — and it has to be an explicit test, because the marker is the one thing that
/// reverses the direction every other case relies on.
#[test]
fn a_trailing_comment_documents_nothing_forwards() {
    let tree = parse("struct S {\n    int a; ///< the a\n    int b;\n};\n");
    let comment = comments(&tree)
        .into_iter()
        .find(|comment| comment.get_comment_text().contains("the a"))
        .expect("the trailing comment");

    assert!(comment.is_trailing(), "the `///<` marker is recognised");
    assert_eq!(
        documented_name(&comment),
        None,
        "a trailing comment documents the member before it, so the forward walk must decline"
    );

    // The declaration it really documents is the one before it, and it is reachable — just not
    // through this accessor.
    //
    // The walk steps over the comment itself, and that step is the shape change rather than a workaround: the comment
    // is now a **sibling** of the members, so the first thing before the member that follows it is the comment. See
    // `a_comment_between_two_members_belongs_to_the_class_body` for why the tree is that way.
    let previous = comment
        .get_owner()
        .and_then(|owner| owner.prev_sibling())
        .and_then(|before| {
            if CppSyntaxKind::from(before.kind()) == CppSyntaxKind::DocComment {
                before.prev_sibling()
            } else {
                Some(before)
            }
        })
        .and_then(CppDeclaration::cast)
        .and_then(|declaration| declaration.get_name_text());
    assert_eq!(
        previous,
        Some("a".to_string()),
        "the member it documents is the declaration before it"
    );
}

/// A comment written the ordinary way is not trailing, whatever else it says.
#[test]
fn only_the_trailing_marker_reverses_the_direction() {
    for source in [
        "/// Doc.\nint x;\n",
        "//! Doc.\nint x;\n",
        "/** Doc. */\nint x;\n",
    ] {
        let comment = the_comment(source);
        assert!(!comment.is_trailing(), "{source:?}");
        assert_eq!(
            documented_name(&comment),
            Some("x".to_string()),
            "{source:?}"
        );
    }
}

/// A preprocessor directive between the comment and the code does not break the relationship: the
/// comment is still about the declaration.
#[test]
fn a_directive_between_the_comment_and_the_declaration_is_stepped_over() {
    assert_eq!(
        documented_name(&the_comment("/// Doc.\n#define N 3\nint x;\n")),
        Some("x".to_string())
    );
}

/// Two comment groups split by a blank line: the second one documents the declaration, and the first
/// documents the second — not the declaration, because they are separate documents.
#[test]
fn separate_comment_groups_do_not_merge() {
    let tree = parse("/// First.\n\n/// Second.\nint x;\n");
    let comments = comments(&tree);
    assert_eq!(comments.len(), 2, "a blank line ends a group");

    assert_eq!(
        documented_name(&comments[1]),
        Some("x".to_string()),
        "the later group documents the declaration"
    );
    assert_eq!(
        documented_name(&comments[0]),
        None,
        "the earlier group documents the later comment, which is not a declaration"
    );
    assert_eq!(
        comments[0]
            .get_owner()
            .map(|node| CppSyntaxKind::from(node.kind())),
        Some(CppSyntaxKind::DocComment),
        "but it does have a following node"
    );
}

/// A comment inside a class body documents the member after it, and a comment between members is a
/// child of the body rather than of either member.
#[test]
fn a_comment_in_a_class_body_documents_the_member_after_it() {
    let tree = parse("struct S {\n    /// The n.\n    int n;\n    int m;\n};\n");
    let comment = comments(&tree).into_iter().next().expect("the comment");

    assert_eq!(documented_name(&comment), Some("n".to_string()));
    assert!(
        comment.get_parent::<cpp_parser::CppClassBody>().is_some(),
        "the comment belongs to the class body, like the members do"
    );
}

/// **A comment between two members belongs to the class body, not to either member.**
///
/// This test used to be `a_comment_after_a_member_is_nested_but_still_finds_its_declaration`, and its own note said
/// what to do when the nesting was fixed: *"this test's first assertion fails and the expectation should be
/// upgraded to 'the comment is a child of the class body'"*. That is what this is.
///
/// The nesting was an accident of the parser rather than a decision — the declaration rule consumed its `;` **and
/// the layout after it** before closing its own node, so the next member's doc comment was emitted inside the
/// declaration above it. The module note at the top of this file already states the shape the tree is supposed to
/// have: a comment between two members belongs to the class body.
///
/// The relationship is read **forwards from the comment** either way, which is the point of testing both halves
/// here: the shape changed and the answer did not, because [`cpp_parser::CppDocComment::get_owner`] walks the tree
/// rather than relying on the comment's parent.
#[test]
fn a_comment_between_two_members_belongs_to_the_class_body() {
    let tree = parse("struct S {\n    int x;\n    /// The y.\n    int y;\n};\n");

    let comment = comments(&tree)
        .into_iter()
        .find(|comment| comment.get_comment_text().contains("The y"))
        .expect("the comment");

    assert_eq!(
        comment.get_parent::<CppDeclaration>(),
        None,
        "the comment is beside the members, not inside the one before it"
    );
    assert_eq!(
        comment
            .syntax()
            .parent()
            .map(|parent| CppSyntaxKind::from(parent.kind())),
        Some(CppSyntaxKind::ClassBody),
        "it is a child of the class body, where a reader sees it"
    );
    assert_eq!(
        documented_name(&comment),
        Some("y".to_string()),
        "and it still documents the member after it, which is the relationship that matters"
    );
}

/// A comment in front of a namespace documents the namespace, which is not a `Declaration` — so the
/// narrow question has no answer while the broad one does.
#[test]
fn a_comment_before_a_namespace_has_an_owner_but_no_declaration() {
    let comment = the_comment("/// Doc.\nnamespace ns { }\n");

    assert_eq!(
        comment
            .get_owner()
            .map(|node| CppSyntaxKind::from(node.kind())),
        Some(CppSyntaxKind::NamespaceDecl)
    );
    assert!(
        comment.get_documented_declaration().is_none(),
        "a namespace is not a declaration node, so it is not the documented declaration"
    );
}

/// A plain comment has the same relationship as a doc comment. It documents nothing to a *renderer*,
/// but the tree does not encode the difference, and a consumer asking about structure should get the
/// structural answer.
#[test]
fn a_plain_comment_has_the_same_relationship() {
    let comment = the_comment("// plain\nint x;\n");

    assert_eq!(documented_name(&comment), Some("x".to_string()));
    assert!(
        !comment.is_documentation(),
        "but it is not documentation, which is a separate question"
    );
}

// ============================================================================
// The relationship survives the whole file
// ============================================================================

/// Every doc comment in a realistic file finds the declaration it describes, in source order.
///
/// The source deliberately stops at the last documented declaration: a comment at the end of a file
/// has nothing after it, which is [`a_comment_at_the_end_of_a_file_documents_nothing`]'s subject.
#[test]
fn every_documented_declaration_in_a_file_is_found() {
    let source = "\
/// A point.
struct Point {
    /// The x.
    int x;
    /// The y.
    int y;
};

/// Distance.
double dist(const Point& a, const Point& b);
";

    let tree = parse(source);
    let names: Vec<Option<String>> = comments(&tree).iter().map(documented_name).collect();

    assert_eq!(
        names,
        vec![
            Some("Point".to_string()),
            Some("x".to_string()),
            Some("y".to_string()),
            Some("dist".to_string()),
        ],
        "every comment that documents something finds it, in source order"
    );
}

// ============================================================================
// The same relationship, read backwards
// ============================================================================

/// The documentation a declaration reports for itself, as a hover asks for it.
///
/// The declaration is found by name so that a test says which one it is asking about, and the answer
/// is the comment's *text*, because that is what a consumer renders.
fn documentation_above(source: &str, name: &str) -> Option<String> {
    let tree = parse(source);
    let declaration = tree
        .get_red_root()
        .descendants()
        .filter_map(CppDeclaration::cast)
        .find(|declaration| declaration.get_name_text().as_deref() == Some(name))
        .unwrap_or_else(|| panic!("{source:?} declares no `{name}`"));

    documentation_of(declaration.syntax()).map(|comment| comment.get_comment_text())
}

/// The one case the forward suite is built on, from the other end: the declaration is asked, not the
/// comment.
#[test]
fn a_declaration_finds_the_comment_above_it() {
    assert_eq!(
        documentation_above("/// Doc.\nint x;\n", "x"),
        Some("Doc.".to_string())
    );
}

/// Every form the forward direction handles, asked backwards.
#[test]
fn every_form_of_declaration_finds_its_comment() {
    let cases = [
        ("/// Doc.\nint f();\n", "f", "Doc."),
        ("/// Doc.\nint x = 1;\n", "x", "Doc."),
        ("/// Doc.\nvoid f() { }\n", "f", "Doc."),
        (
            "/// A grid.\nclass Grid {\n    int n;\n};\n",
            "Grid",
            "A grid.",
        ),
    ];

    for (source, name, expected) in cases {
        assert_eq!(
            documentation_above(source, name),
            Some(expected.to_string()),
            "{source:?}"
        );
    }
}

/// A directive between the comment and the declaration is stepped over — the forward walk's rule, so
/// the reverse walk has to step over it too.
#[test]
fn the_reverse_walk_steps_over_a_directive() {
    assert_eq!(
        documentation_above("/// Doc.\n#define N 3\nint x;\n", "x"),
        Some("Doc.".to_string())
    );
}

/// A comment directly above a member of a class body documents that member.
#[test]
fn a_member_finds_the_comment_above_it() {
    let source = "struct S {\n    /// The n.\n    int n;\n    int m;\n};\n";

    assert_eq!(documentation_above(source, "n"), Some("The n.".to_string()));
    assert_eq!(
        documentation_above(source, "m"),
        None,
        "the comment above `n` is not borrowed by the member after it"
    );
}

/// **The nesting wart, read backwards.**
///
/// A comment written after a member is emitted *inside* that member's declaration (see
/// [`a_comment_after_a_member_is_nested_but_still_finds_its_declaration`]), so the comment above `y`
/// is the last child of `x`. The reverse walk has to look *inside* the construct before it, not only
/// at comment siblings, or every member but the first would appear undocumented.
#[test]
fn a_member_finds_a_comment_nested_in_the_member_before_it() {
    assert_eq!(
        documentation_above(
            "struct S {\n    int x;\n    /// The y.\n    int y;\n};\n",
            "y"
        ),
        Some("The y.".to_string())
    );
}

/// A trailing `///<` documents the member before it, so it is not the documentation of the member
/// after it. The forward accessor declines it, and the reverse lookup has to as well — otherwise
/// `int a; ///< the a` would be read as documentation of `b`, and the popup would describe the wrong
/// member.
#[test]
fn a_trailing_comment_does_not_document_what_follows() {
    let source = "struct S {\n    int a; ///< the a\n    int b;\n};\n";

    assert_eq!(documentation_above(source, "b"), None);
    assert_eq!(
        documentation_above(source, "a"),
        None,
        "and the member it does document is not reachable forwards either — the parser declines the \
         marker rather than following it backwards"
    );
}

/// A comment documents the declaration *after* it and nothing else: the declaration below the next
/// one is not documented by the same comment.
#[test]
fn a_comment_is_not_borrowed_by_the_second_declaration_after_it() {
    let source = "/// First.\nint a;\nint b;\n";

    assert_eq!(documentation_above(source, "a"), Some("First.".to_string()));
    assert_eq!(documentation_above(source, "b"), None);
}

/// A comment above a class documents the class, not its first member: the walk leaves the class body
/// looking for a construct before it, finds the class's own comment, and the forward accessor rejects
/// it for the member.
#[test]
fn a_class_comment_is_not_the_documentation_of_its_first_member() {
    let source = "/// The point.\nstruct Point {\n    int x;\n};\n";

    assert_eq!(
        documentation_above(source, "Point"),
        Some("The point.".to_string())
    );
    assert_eq!(documentation_above(source, "x"), None);
}

/// A blank line ends a comment group, so the group nearer the declaration is the one that documents
/// it.
#[test]
fn the_group_nearest_the_declaration_is_the_one_found() {
    assert_eq!(
        documentation_above("/// First.\n\n/// Second.\nint x;\n", "x"),
        Some("Second.".to_string())
    );
}

/// A file whose declarations are all documented round-trips: every declaration finds its own comment,
/// which is the forward suite's [`every_documented_declaration_in_a_file_is_found`] asked the other
/// way.
#[test]
fn every_declaration_in_a_file_finds_its_comment() {
    let source = "\
/// A point.
struct Point {
    /// The x.
    int x;
    /// The y.
    int y;
};

/// Distance.
double dist(const Point& a, const Point& b);
";

    let tree = parse(source);
    let found: Vec<(String, Option<String>)> = tree
        .get_red_root()
        .descendants()
        .filter_map(CppDeclaration::cast)
        .filter_map(|declaration| {
            let name = declaration.get_name_text()?;
            let documentation =
                documentation_of(declaration.syntax()).map(|comment| comment.get_comment_text());
            Some((name, documentation))
        })
        .collect();

    assert_eq!(
        found,
        vec![
            ("Point".to_string(), Some("A point.".to_string())),
            ("x".to_string(), Some("The x.".to_string())),
            ("y".to_string(), Some("The y.".to_string())),
            ("dist".to_string(), Some("Distance.".to_string())),
        ]
    );
}