clang 20.0.0git
Classes | Typedefs | Enumerations | Functions
Comment introspection

The routines in this group provide access to information in documentation comments. More...

Classes

struct  CXComment
 A parsed comment. More...
 

Typedefs

typedef struct CXAPISetImpl * CXAPISet
 CXAPISet is an opaque type that represents a data structure containing all the API information for a given translation unit.
 

Enumerations

enum  CXCommentKind {
  CXComment_Null = 0 , CXComment_Text = 1 , CXComment_InlineCommand = 2 , CXComment_HTMLStartTag = 3 ,
  CXComment_HTMLEndTag = 4 , CXComment_Paragraph = 5 , CXComment_BlockCommand = 6 , CXComment_ParamCommand = 7 ,
  CXComment_TParamCommand = 8 , CXComment_VerbatimBlockCommand = 9 , CXComment_VerbatimBlockLine = 10 , CXComment_VerbatimLine = 11 ,
  CXComment_FullComment = 12
}
 Describes the type of the comment AST node (CXComment). More...
 
enum  CXCommentInlineCommandRenderKind {
  CXCommentInlineCommandRenderKind_Normal , CXCommentInlineCommandRenderKind_Bold , CXCommentInlineCommandRenderKind_Monospaced , CXCommentInlineCommandRenderKind_Emphasized ,
  CXCommentInlineCommandRenderKind_Anchor
}
 The most appropriate rendering mode for an inline command, chosen on command semantics in Doxygen. More...
 
enum  CXCommentParamPassDirection { CXCommentParamPassDirection_In , CXCommentParamPassDirection_Out , CXCommentParamPassDirection_InOut }
 Describes parameter passing direction for \param or \arg command. More...
 

Functions

CINDEX_LINKAGE CXComment clang_Cursor_getParsedComment (CXCursor C)
 Given a cursor that represents a documentable entity (e.g., declaration), return the associated parsed comment as a CXComment_FullComment AST node.
 
CINDEX_LINKAGE enum CXCommentKind clang_Comment_getKind (CXComment Comment)
 
CINDEX_LINKAGE unsigned clang_Comment_getNumChildren (CXComment Comment)
 
CINDEX_LINKAGE CXComment clang_Comment_getChild (CXComment Comment, unsigned ChildIdx)
 
CINDEX_LINKAGE unsigned clang_Comment_isWhitespace (CXComment Comment)
 A CXComment_Paragraph node is considered whitespace if it contains only CXComment_Text nodes that are empty or whitespace.
 
CINDEX_LINKAGE unsigned clang_InlineContentComment_hasTrailingNewline (CXComment Comment)
 
CINDEX_LINKAGE CXString clang_TextComment_getText (CXComment Comment)
 
CINDEX_LINKAGE CXString clang_InlineCommandComment_getCommandName (CXComment Comment)
 
CINDEX_LINKAGE enum CXCommentInlineCommandRenderKind clang_InlineCommandComment_getRenderKind (CXComment Comment)
 
CINDEX_LINKAGE unsigned clang_InlineCommandComment_getNumArgs (CXComment Comment)
 
CINDEX_LINKAGE CXString clang_InlineCommandComment_getArgText (CXComment Comment, unsigned ArgIdx)
 
CINDEX_LINKAGE CXString clang_HTMLTagComment_getTagName (CXComment Comment)
 
CINDEX_LINKAGE unsigned clang_HTMLStartTagComment_isSelfClosing (CXComment Comment)
 
CINDEX_LINKAGE unsigned clang_HTMLStartTag_getNumAttrs (CXComment Comment)
 
CINDEX_LINKAGE CXString clang_HTMLStartTag_getAttrName (CXComment Comment, unsigned AttrIdx)
 
CINDEX_LINKAGE CXString clang_HTMLStartTag_getAttrValue (CXComment Comment, unsigned AttrIdx)
 
CINDEX_LINKAGE CXString clang_BlockCommandComment_getCommandName (CXComment Comment)
 
CINDEX_LINKAGE unsigned clang_BlockCommandComment_getNumArgs (CXComment Comment)
 
CINDEX_LINKAGE CXString clang_BlockCommandComment_getArgText (CXComment Comment, unsigned ArgIdx)
 
CINDEX_LINKAGE CXComment clang_BlockCommandComment_getParagraph (CXComment Comment)
 
CINDEX_LINKAGE CXString clang_ParamCommandComment_getParamName (CXComment Comment)
 
CINDEX_LINKAGE unsigned clang_ParamCommandComment_isParamIndexValid (CXComment Comment)
 
CINDEX_LINKAGE unsigned clang_ParamCommandComment_getParamIndex (CXComment Comment)
 
CINDEX_LINKAGE unsigned clang_ParamCommandComment_isDirectionExplicit (CXComment Comment)
 
CINDEX_LINKAGE enum CXCommentParamPassDirection clang_ParamCommandComment_getDirection (CXComment Comment)
 
CINDEX_LINKAGE CXString clang_TParamCommandComment_getParamName (CXComment Comment)
 
CINDEX_LINKAGE unsigned clang_TParamCommandComment_isParamPositionValid (CXComment Comment)
 
CINDEX_LINKAGE unsigned clang_TParamCommandComment_getDepth (CXComment Comment)
 
CINDEX_LINKAGE unsigned clang_TParamCommandComment_getIndex (CXComment Comment, unsigned Depth)
 
CINDEX_LINKAGE CXString clang_VerbatimBlockLineComment_getText (CXComment Comment)
 
CINDEX_LINKAGE CXString clang_VerbatimLineComment_getText (CXComment Comment)
 
CINDEX_LINKAGE CXString clang_HTMLTagComment_getAsString (CXComment Comment)
 Convert an HTML tag AST node to string.
 
CINDEX_LINKAGE CXString clang_FullComment_getAsHTML (CXComment Comment)
 Convert a given full parsed comment to an HTML fragment.
 
CINDEX_LINKAGE CXString clang_FullComment_getAsXML (CXComment Comment)
 Convert a given full parsed comment to an XML document.
 
CINDEX_LINKAGE enum CXErrorCode clang_createAPISet (CXTranslationUnit tu, CXAPISet *out_api)
 Traverses the translation unit to create a CXAPISet.
 
CINDEX_LINKAGE void clang_disposeAPISet (CXAPISet api)
 Dispose of an APISet.
 
CINDEX_LINKAGE CXString clang_getSymbolGraphForUSR (const char *usr, CXAPISet api)
 Generate a single symbol symbol graph for the given USR.
 
CINDEX_LINKAGE CXString clang_getSymbolGraphForCursor (CXCursor cursor)
 Generate a single symbol symbol graph for the declaration at the given cursor.
 

Detailed Description

The routines in this group provide access to information in documentation comments.

These facilities are distinct from the core and may be subject to their own schedule of stability and deprecation.

Typedef Documentation

◆ CXAPISet

typedef struct CXAPISetImpl* CXAPISet

CXAPISet is an opaque type that represents a data structure containing all the API information for a given translation unit.

This can be used for a single symbol symbol graph for a given symbol.

Definition at line 554 of file Documentation.h.

Enumeration Type Documentation

◆ CXCommentInlineCommandRenderKind

The most appropriate rendering mode for an inline command, chosen on command semantics in Doxygen.

Enumerator
CXCommentInlineCommandRenderKind_Normal 

Command argument should be rendered in a normal font.

CXCommentInlineCommandRenderKind_Bold 

Command argument should be rendered in a bold font.

CXCommentInlineCommandRenderKind_Monospaced 

Command argument should be rendered in a monospaced font.

CXCommentInlineCommandRenderKind_Emphasized 

Command argument should be rendered emphasized (typically italic font).

CXCommentInlineCommandRenderKind_Anchor 

Command argument should not be rendered (since it only defines an anchor).

Definition at line 165 of file Documentation.h.

◆ CXCommentKind

Describes the type of the comment AST node (CXComment).

A comment node can be considered block content (e. g., paragraph), inline content (plain text) or neither (the root AST node).

Enumerator
CXComment_Null 

Null comment.

No AST node is constructed at the requested location because there is no text or a syntax error.

CXComment_Text 

Plain text.

Inline content.

CXComment_InlineCommand 

A command with word-like arguments that is considered inline content.

For example: \c command.

CXComment_HTMLStartTag 

HTML start tag with attributes (name-value pairs).

Considered inline content.

For example:

* <br> <br /> <a href="http://example.org/">
* 
CXComment_HTMLEndTag 

HTML end tag.

Considered inline content.

For example:

* </a>
* 
CXComment_Paragraph 

A paragraph, contains inline comment.

The paragraph itself is block content.

CXComment_BlockCommand 

A command that has zero or more word-like arguments (number of word-like arguments depends on command name) and a paragraph as an argument.

Block command is block content.

Paragraph argument is also a child of the block command.

For example: \has 0 word-like arguments and a paragraph argument.

AST nodes of special kinds that parser knows about (e. g., \param command) have their own node kinds.

CXComment_ParamCommand 

A \param or \arg command that describes the function parameter (name, passing direction, description).

For example: \param [in] ParamName description.

CXComment_TParamCommand 

A \tparam command that describes a template parameter (name and description).

For example: \tparam T description.

CXComment_VerbatimBlockCommand 

A verbatim block command (e.

g., preformatted code). Verbatim block has an opening and a closing command and contains multiple lines of text (CXComment_VerbatimBlockLine child nodes).

For example: \verbatim aaa \endverbatim

CXComment_VerbatimBlockLine 

A line of text that is contained within a CXComment_VerbatimBlockCommand node.

CXComment_VerbatimLine 

A verbatim line command.

Verbatim line has an opening command, a single line of text (up to the newline after the opening command) and has no closing command.

CXComment_FullComment 

A full comment attached to a declaration, contains block content.

Definition at line 54 of file Documentation.h.

◆ CXCommentParamPassDirection

Describes parameter passing direction for \param or \arg command.

Enumerator
CXCommentParamPassDirection_In 

The parameter is an input parameter.

CXCommentParamPassDirection_Out 

The parameter is an output parameter.

CXCommentParamPassDirection_InOut 

The parameter is an input and output parameter.

Definition at line 196 of file Documentation.h.

Function Documentation

◆ clang_BlockCommandComment_getArgText()

CINDEX_LINKAGE CXString clang_BlockCommandComment_getArgText ( CXComment  Comment,
unsigned  ArgIdx 
)
Parameters
Commenta CXComment_BlockCommand AST node.
ArgIdxargument index (zero-based).
Returns
text of the specified word-like argument.

◆ clang_BlockCommandComment_getCommandName()

CINDEX_LINKAGE CXString clang_BlockCommandComment_getCommandName ( CXComment  Comment)
Parameters
Commenta CXComment_BlockCommand AST node.
Returns
name of the block command.

◆ clang_BlockCommandComment_getNumArgs()

CINDEX_LINKAGE unsigned clang_BlockCommandComment_getNumArgs ( CXComment  Comment)
Parameters
Commenta CXComment_BlockCommand AST node.
Returns
number of word-like arguments.

◆ clang_BlockCommandComment_getParagraph()

CINDEX_LINKAGE CXComment clang_BlockCommandComment_getParagraph ( CXComment  Comment)
Parameters
Commenta CXComment_BlockCommand or CXComment_VerbatimBlockCommand AST node.
Returns
paragraph argument of the block command.

◆ clang_Comment_getChild()

CINDEX_LINKAGE CXComment clang_Comment_getChild ( CXComment  Comment,
unsigned  ChildIdx 
)
Parameters
CommentAST node of any kind.
ChildIdxchild index (zero-based).
Returns
the specified child of the AST node.

◆ clang_Comment_getKind()

CINDEX_LINKAGE enum CXCommentKind clang_Comment_getKind ( CXComment  Comment)
Parameters
CommentAST node of any kind.
Returns
the type of the AST node.

◆ clang_Comment_getNumChildren()

CINDEX_LINKAGE unsigned clang_Comment_getNumChildren ( CXComment  Comment)
Parameters
CommentAST node of any kind.
Returns
number of children of the AST node.

◆ clang_Comment_isWhitespace()

CINDEX_LINKAGE unsigned clang_Comment_isWhitespace ( CXComment  Comment)

A CXComment_Paragraph node is considered whitespace if it contains only CXComment_Text nodes that are empty or whitespace.

Other AST nodes (except CXComment_Paragraph and CXComment_Text) are never considered whitespace.

Returns
non-zero if Comment is whitespace.

◆ clang_createAPISet()

CINDEX_LINKAGE enum CXErrorCode clang_createAPISet ( CXTranslationUnit  tu,
CXAPISet out_api 
)

Traverses the translation unit to create a CXAPISet.

Parameters
tuis the CXTranslationUnit to build the CXAPISet for.
out_apiis a pointer to the output of this function. It is needs to be disposed of by calling clang_disposeAPISet.
Returns
Error code indicating success or failure of the APISet creation.

◆ clang_Cursor_getParsedComment()

CINDEX_LINKAGE CXComment clang_Cursor_getParsedComment ( CXCursor  C)

Given a cursor that represents a documentable entity (e.g., declaration), return the associated parsed comment as a CXComment_FullComment AST node.

◆ clang_disposeAPISet()

CINDEX_LINKAGE void clang_disposeAPISet ( CXAPISet  api)

Dispose of an APISet.

The provided CXAPISet can not be used after this function is called.

◆ clang_FullComment_getAsHTML()

CINDEX_LINKAGE CXString clang_FullComment_getAsHTML ( CXComment  Comment)

Convert a given full parsed comment to an HTML fragment.

Specific details of HTML layout are subject to change. Don't try to parse this HTML back into an AST, use other APIs instead.

Currently the following CSS classes are used:

  • "para-brief" for

equivalent commands;

  • "para-returns" for \returns paragraph and equivalent commands;
  • "word-returns" for the "Returns" word in \returns paragraph.

Function argument documentation is rendered as a <dl> list with arguments sorted in function prototype order. CSS classes used:

  • "param-name-index-NUMBER" for parameter name (<dt>);
  • "param-descr-index-NUMBER" for parameter description (<dd>);
  • "param-name-index-invalid" and "param-descr-index-invalid" are used if parameter index is invalid.

Template parameter documentation is rendered as a <dl> list with parameters sorted in template parameter list order. CSS classes used:

  • "tparam-name-index-NUMBER" for parameter name (<dt>);
  • "tparam-descr-index-NUMBER" for parameter description (<dd>);
  • "tparam-name-index-other" and "tparam-descr-index-other" are used for names inside template template parameters;
  • "tparam-name-index-invalid" and "tparam-descr-index-invalid" are used if parameter position is invalid.
Parameters
Commenta CXComment_FullComment AST node.
Returns
string containing an HTML fragment.

◆ clang_FullComment_getAsXML()

CINDEX_LINKAGE CXString clang_FullComment_getAsXML ( CXComment  Comment)

Convert a given full parsed comment to an XML document.

A Relax NG schema for the XML can be found in comment-xml-schema.rng file inside clang source tree.

Parameters
Commenta CXComment_FullComment AST node.
Returns
string containing an XML document.

◆ clang_getSymbolGraphForCursor()

CINDEX_LINKAGE CXString clang_getSymbolGraphForCursor ( CXCursor  cursor)

Generate a single symbol symbol graph for the declaration at the given cursor.

Returns a null string if the AST node for the cursor isn't a declaration.

The output contains the symbol graph as well as some additional information about related symbols.

Parameters
cursorthe declaration for which to generate the single symbol symbol graph.
Returns
a string containing the serialized symbol graph representation for the symbol being queried or a null string if it can not be found in the APISet.

◆ clang_getSymbolGraphForUSR()

CINDEX_LINKAGE CXString clang_getSymbolGraphForUSR ( const char *  usr,
CXAPISet  api 
)

Generate a single symbol symbol graph for the given USR.

Returns a null string if the associated symbol can not be found in the provided CXAPISet.

The output contains the symbol graph as well as some additional information about related symbols.

Parameters
usris a string containing the USR of the symbol to generate the symbol graph for.
apithe CXAPISet to look for the symbol in.
Returns
a string containing the serialized symbol graph representation for the symbol being queried or a null string if it can not be found in the APISet.

◆ clang_HTMLStartTag_getAttrName()

CINDEX_LINKAGE CXString clang_HTMLStartTag_getAttrName ( CXComment  Comment,
unsigned  AttrIdx 
)
Parameters
Commenta CXComment_HTMLStartTag AST node.
AttrIdxattribute index (zero-based).
Returns
name of the specified attribute.

◆ clang_HTMLStartTag_getAttrValue()

CINDEX_LINKAGE CXString clang_HTMLStartTag_getAttrValue ( CXComment  Comment,
unsigned  AttrIdx 
)
Parameters
Commenta CXComment_HTMLStartTag AST node.
AttrIdxattribute index (zero-based).
Returns
value of the specified attribute.

◆ clang_HTMLStartTag_getNumAttrs()

CINDEX_LINKAGE unsigned clang_HTMLStartTag_getNumAttrs ( CXComment  Comment)
Parameters
Commenta CXComment_HTMLStartTag AST node.
Returns
number of attributes (name-value pairs) attached to the start tag.

◆ clang_HTMLStartTagComment_isSelfClosing()

CINDEX_LINKAGE unsigned clang_HTMLStartTagComment_isSelfClosing ( CXComment  Comment)
Parameters
Commenta CXComment_HTMLStartTag AST node.
Returns
non-zero if tag is self-closing (for example, <br />).

◆ clang_HTMLTagComment_getAsString()

CINDEX_LINKAGE CXString clang_HTMLTagComment_getAsString ( CXComment  Comment)

Convert an HTML tag AST node to string.

Parameters
Commenta CXComment_HTMLStartTag or CXComment_HTMLEndTag AST node.
Returns
string containing an HTML tag.

◆ clang_HTMLTagComment_getTagName()

CINDEX_LINKAGE CXString clang_HTMLTagComment_getTagName ( CXComment  Comment)
Parameters
Commenta CXComment_HTMLStartTag or CXComment_HTMLEndTag AST node.
Returns
HTML tag name.

◆ clang_InlineCommandComment_getArgText()

CINDEX_LINKAGE CXString clang_InlineCommandComment_getArgText ( CXComment  Comment,
unsigned  ArgIdx 
)
Parameters
Commenta CXComment_InlineCommand AST node.
ArgIdxargument index (zero-based).
Returns
text of the specified argument.

◆ clang_InlineCommandComment_getCommandName()

CINDEX_LINKAGE CXString clang_InlineCommandComment_getCommandName ( CXComment  Comment)
Parameters
Commenta CXComment_InlineCommand AST node.
Returns
name of the inline command.

◆ clang_InlineCommandComment_getNumArgs()

CINDEX_LINKAGE unsigned clang_InlineCommandComment_getNumArgs ( CXComment  Comment)
Parameters
Commenta CXComment_InlineCommand AST node.
Returns
number of command arguments.

◆ clang_InlineCommandComment_getRenderKind()

CINDEX_LINKAGE enum CXCommentInlineCommandRenderKind clang_InlineCommandComment_getRenderKind ( CXComment  Comment)
Parameters
Commenta CXComment_InlineCommand AST node.
Returns
the most appropriate rendering mode, chosen on command semantics in Doxygen.

◆ clang_InlineContentComment_hasTrailingNewline()

CINDEX_LINKAGE unsigned clang_InlineContentComment_hasTrailingNewline ( CXComment  Comment)
Returns
non-zero if Comment is inline content and has a newline immediately following it in the comment text. Newlines between paragraphs do not count.

◆ clang_ParamCommandComment_getDirection()

CINDEX_LINKAGE enum CXCommentParamPassDirection clang_ParamCommandComment_getDirection ( CXComment  Comment)
Parameters
Commenta CXComment_ParamCommand AST node.
Returns
parameter passing direction.

◆ clang_ParamCommandComment_getParamIndex()

CINDEX_LINKAGE unsigned clang_ParamCommandComment_getParamIndex ( CXComment  Comment)
Parameters
Commenta CXComment_ParamCommand AST node.
Returns
zero-based parameter index in function prototype.

◆ clang_ParamCommandComment_getParamName()

CINDEX_LINKAGE CXString clang_ParamCommandComment_getParamName ( CXComment  Comment)
Parameters
Commenta CXComment_ParamCommand AST node.
Returns
parameter name.

◆ clang_ParamCommandComment_isDirectionExplicit()

CINDEX_LINKAGE unsigned clang_ParamCommandComment_isDirectionExplicit ( CXComment  Comment)
Parameters
Commenta CXComment_ParamCommand AST node.
Returns
non-zero if parameter passing direction was specified explicitly in the comment.

◆ clang_ParamCommandComment_isParamIndexValid()

CINDEX_LINKAGE unsigned clang_ParamCommandComment_isParamIndexValid ( CXComment  Comment)
Parameters
Commenta CXComment_ParamCommand AST node.
Returns
non-zero if the parameter that this AST node represents was found in the function prototype and clang_ParamCommandComment_getParamIndex function will return a meaningful value.

◆ clang_TextComment_getText()

CINDEX_LINKAGE CXString clang_TextComment_getText ( CXComment  Comment)
Parameters
Commenta CXComment_Text AST node.
Returns
text contained in the AST node.

◆ clang_TParamCommandComment_getDepth()

CINDEX_LINKAGE unsigned clang_TParamCommandComment_getDepth ( CXComment  Comment)
Parameters
Commenta CXComment_TParamCommand AST node.
Returns
zero-based nesting depth of this parameter in the template parameter list.

For example,

*     template<typename C, template<typename T> class TT>
*     void test(TT<int> aaa);
* 

for C and TT nesting depth is 0, for T nesting depth is 1.

◆ clang_TParamCommandComment_getIndex()

CINDEX_LINKAGE unsigned clang_TParamCommandComment_getIndex ( CXComment  Comment,
unsigned  Depth 
)
Parameters
Commenta CXComment_TParamCommand AST node.
Returns
zero-based parameter index in the template parameter list at a given nesting depth.

For example,

*     template<typename C, template<typename T> class TT>
*     void test(TT<int> aaa);
* 

for C and TT nesting depth is 0, so we can ask for index at depth 0: at depth 0 C's index is 0, TT's index is 1.

For T nesting depth is 1, so we can ask for index at depth 0 and 1: at depth 0 T's index is 1 (same as TT's), at depth 1 T's index is 0.

◆ clang_TParamCommandComment_getParamName()

CINDEX_LINKAGE CXString clang_TParamCommandComment_getParamName ( CXComment  Comment)
Parameters
Commenta CXComment_TParamCommand AST node.
Returns
template parameter name.

◆ clang_TParamCommandComment_isParamPositionValid()

CINDEX_LINKAGE unsigned clang_TParamCommandComment_isParamPositionValid ( CXComment  Comment)
Parameters
Commenta CXComment_TParamCommand AST node.
Returns
non-zero if the parameter that this AST node represents was found in the template parameter list and clang_TParamCommandComment_getDepth and clang_TParamCommandComment_getIndex functions will return a meaningful value.

◆ clang_VerbatimBlockLineComment_getText()

CINDEX_LINKAGE CXString clang_VerbatimBlockLineComment_getText ( CXComment  Comment)
Parameters
Commenta CXComment_VerbatimBlockLine AST node.
Returns
text contained in the AST node.

◆ clang_VerbatimLineComment_getText()

CINDEX_LINKAGE CXString clang_VerbatimLineComment_getText ( CXComment  Comment)
Parameters
Commenta CXComment_VerbatimLine AST node.
Returns
text contained in the AST node.