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

enum 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

enum 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

enum 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

Comment	a CXComment_BlockCommand AST node.
ArgIdx	argument index (zero-based).

Returns

text of the specified word-like argument.

clang_BlockCommandComment_getCommandName()

CINDEX_LINKAGE CXString clang_BlockCommandComment_getCommandName

(

CXComment

Comment

)

Parameters

Comment

a CXComment_BlockCommand AST node.

Returns

name of the block command.

clang_BlockCommandComment_getNumArgs()

CINDEX_LINKAGE unsigned clang_BlockCommandComment_getNumArgs

(

CXComment

Comment

)

Parameters

Comment

a CXComment_BlockCommand AST node.

Returns

number of word-like arguments.

clang_BlockCommandComment_getParagraph()

CINDEX_LINKAGE CXComment clang_BlockCommandComment_getParagraph

(

CXComment

Comment

)

Parameters

Comment

a 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

Comment	AST node of any kind.
ChildIdx	child index (zero-based).

Returns

the specified child of the AST node.

clang_Comment_getKind()

CINDEX_LINKAGE enum CXCommentKind clang_Comment_getKind

(

CXComment

Comment

)

Parameters

Comment

AST node of any kind.

Returns

the type of the AST node.

clang_Comment_getNumChildren()

CINDEX_LINKAGE unsigned clang_Comment_getNumChildren

(

CXComment

Comment

)

Parameters

Comment

AST 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

tu	is the CXTranslationUnit to build the CXAPISet for.
out_api	is 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

Comment

a 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

Comment

a 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

cursor

the 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

usr	is a string containing the USR of the symbol to generate the symbol graph for.
api	the 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

Comment	a CXComment_HTMLStartTag AST node.
AttrIdx	attribute index (zero-based).

Returns

name of the specified attribute.

clang_HTMLStartTag_getAttrValue()

CINDEX_LINKAGE CXString clang_HTMLStartTag_getAttrValue	(	CXComment	Comment,
		unsigned	AttrIdx
	)

Parameters

Comment	a CXComment_HTMLStartTag AST node.
AttrIdx	attribute index (zero-based).

Returns

value of the specified attribute.

clang_HTMLStartTag_getNumAttrs()

CINDEX_LINKAGE unsigned clang_HTMLStartTag_getNumAttrs

(

CXComment

Comment

)

Parameters

Comment

a 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

Comment

a 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

Comment

a 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

Comment

a 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

Comment	a CXComment_InlineCommand AST node.
ArgIdx	argument index (zero-based).

Returns

text of the specified argument.

clang_InlineCommandComment_getCommandName()

CINDEX_LINKAGE CXString clang_InlineCommandComment_getCommandName

(

CXComment

Comment

)

Parameters

Comment

a CXComment_InlineCommand AST node.

Returns

name of the inline command.

clang_InlineCommandComment_getNumArgs()

CINDEX_LINKAGE unsigned clang_InlineCommandComment_getNumArgs

(

CXComment

Comment

)

Parameters

Comment

a CXComment_InlineCommand AST node.

Returns

number of command arguments.

clang_InlineCommandComment_getRenderKind()

CINDEX_LINKAGE enum CXCommentInlineCommandRenderKind clang_InlineCommandComment_getRenderKind

(

CXComment

Comment

)

Parameters

Comment

a 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

Comment

a CXComment_ParamCommand AST node.

Returns

parameter passing direction.

clang_ParamCommandComment_getParamIndex()

CINDEX_LINKAGE unsigned clang_ParamCommandComment_getParamIndex

(

CXComment

Comment

)

Parameters

Comment

a CXComment_ParamCommand AST node.

Returns

zero-based parameter index in function prototype.

clang_ParamCommandComment_getParamName()

CINDEX_LINKAGE CXString clang_ParamCommandComment_getParamName

(

CXComment

Comment

)

Parameters

Comment

a CXComment_ParamCommand AST node.

Returns

parameter name.

clang_ParamCommandComment_isDirectionExplicit()

CINDEX_LINKAGE unsigned clang_ParamCommandComment_isDirectionExplicit

(

CXComment

Comment

)

Parameters

Comment

a 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

Comment

a 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

Comment

a CXComment_Text AST node.

Returns

text contained in the AST node.

clang_TParamCommandComment_getDepth()

CINDEX_LINKAGE unsigned clang_TParamCommandComment_getDepth

(

CXComment

Comment

)

Parameters

Comment

a 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

Comment

a 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

Comment

a CXComment_TParamCommand AST node.

Returns

template parameter name.

clang_TParamCommandComment_isParamPositionValid()

CINDEX_LINKAGE unsigned clang_TParamCommandComment_isParamPositionValid

(

CXComment

Comment

)

Parameters

Comment

a 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

Comment

a CXComment_VerbatimBlockLine AST node.

Returns

text contained in the AST node.

clang_VerbatimLineComment_getText()

CINDEX_LINKAGE CXString clang_VerbatimLineComment_getText

(

CXComment

Comment

)

Parameters

Comment

a CXComment_VerbatimLine AST node.

Returns

text contained in the AST node.