Skip to content

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

Open
@Nerixyz

Description

@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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    clang:frontendLanguage frontend issues, e.g. anything involving "Sema"

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions