[Clang] HTML comments inside C comments are treated as text

[Nerixyz]

I mentioned this briefly in #120843 (comment).

The CommentParser currently emits HTML comments (/* <!-- foo --> */) as text:

/// <!-- foo
/// bar
///
/// baz -->
/// <!--! text -->
int Test;

Leads to:

VarDecl 0x30543910 <<source>:6:1, col:5> col:5 Test 'int'
`-FullComment 0x30543b90 <line:1:4, line:5:18>
  |-ParagraphComment 0x30543aa0 <line:1:4, line:2:7>
  | |-TextComment 0x30543a00 <line:1:4> Text=" "
  | |-TextComment 0x30543a20 <col:5> Text="<"
  | |-TextComment 0x30543a40 <col:6, col:12> Text="!-- foo"
  | `-TextComment 0x30543a60 <line:2:4, col:7> Text=" bar"
  `-ParagraphComment 0x30543b60 <line:4:4, line:5:18>
    |-TextComment 0x30543ac0 <line:4:4, col:11> Text=" baz -->"
    |-TextComment 0x30543ae0 <line:5:4> Text=" "
    |-TextComment 0x30543b00 <col:5> Text="<"
    `-TextComment 0x30543b20 <col:6, col:18> Text="!--! text -->"

https://godbolt.org/z/sonfj47xo

Doxygen however ignores HTML comments (docs).

I can see two possible strategies here:

1. Mirror Doxygen - skip anything between <!-- and --> and include the content between <!--! and -->.
2. Emit a dedicated HTMLComment(Comment) which contains the text inside the comment (<!-- ... -->) and DoxygenHTMLComment(Comment) that contains a subtree of a parsed comment (<!--! ... -->). Not sure about the naming.

1 is easier to implement and has better backwards compatibility. 2 might be useful for tools that specifically want to extract these fragments (e.g. because they contain some commands for the tool that shouldn't be shown in Doxygen). I'm not sure what the best approach is.

[llvmbot]

@llvm/issue-subscribers-clang-frontend

Author: nerix (Nerixyz)

I mentioned this briefly in https://github.com//pull/120843#issuecomment-2593556040.

The CommentParser currently emits HTML comments (/* <!-- foo --> */) as text:

/// <!-- foo
/// bar
///
/// baz -->
/// <!--! text -->
int Test;

Leads to:

VarDecl 0x30543910 <<source>:6:1, col:5> col:5 Test 'int'
`-FullComment 0x30543b90 <line:1:4, line:5:18>
  |-ParagraphComment 0x30543aa0 <line:1:4, line:2:7>
  | |-TextComment 0x30543a00 <line:1:4> Text=" "
  | |-TextComment 0x30543a20 <col:5> Text="<"
  | |-TextComment 0x30543a40 <col:6, col:12> Text="!-- foo"
  | `-TextComment 0x30543a60 <line:2:4, col:7> Text=" bar"
  `-ParagraphComment 0x30543b60 <line:4:4, line:5:18>
    |-TextComment 0x30543ac0 <line:4:4, col:11> Text=" baz -->"
    |-TextComment 0x30543ae0 <line:5:4> Text=" "
    |-TextComment 0x30543b00 <col:5> Text="<"
    `-TextComment 0x30543b20 <col:6, col:18> Text="!--! text -->"

https://godbolt.org/z/sonfj47xo

Doxygen however ignores HTML comments (docs).

I can see two possible strategies here:

1. Mirror Doxygen - skip anything between <!-- and --> and include the content between <!--! and -->.
2. Emit a dedicated HTMLComment(Comment) which contains the text inside the comment (<!-- ... -->) and DoxygenHTMLComment(Comment) that contains a subtree of a parsed comment (<!--! ... -->). Not sure about the naming.

1 is easier to implement and has better backwards compatibility. 2 might be useful for tools that specifically want to extract these fragments (e.g. because they contain some commands for the tool that shouldn't be shown in Doxygen). I'm not sure what the best approach is.