Skip to content

[clang] Clang doesn't support parsing Doxygen group comments #151184

@evelez7

Description

@evelez7

Clang currently doesn’t support Doxygen grouping in its comment parsing. Member groups allow for declarations to be specially grouped in documentation under the same heading or to share the same documentation. Grouping is fairly common in Clang and LLVM and Clang-Doc’s documentation would benefit from being able to display them. Grouping is fairly complex and there are a few variations, so an initial implementation should focus on member grouping first, and incorporate more functionality over time.

Doxygen grouping looks like the following:

/// \name Group
/// \{
void func1();

void func2();
/// \}

func1 and func2 will then be grouped under the heading “Group” in documentation while retaining their own documentation. See sys::path for examples in documentation ("Lexical Component Iterator", etc).

To implement this, Clang would need to recognize the special command’s start and ending (\{ and ‘}), the \name` command, and then be able to track the declarations within those braces. It would also need to keep track of the context when parsing other comments (i.e. know that we encountered an opening brace for some other declaration and now we found a closing one, then group or mark those declarations). At a glance, it seems like marking or grouping these declarations somewhere during comment parsing would be the most difficult part of this.

/// \{
/// This comment is associated with Foo in the AST.

class Foo;

/// \}
///This comment is associated with Bar in the AST.

class Bar;

Metadata

Metadata

Assignees

No one assigned

    Labels

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

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions