Clang.Comment

Functions for traversing the comment AST and analyzing the nodes it contains.

To start traversing the comment AST, use getParsedComment to retrieve the comment from an AST node that may be associated with one (for example, any kind of declaration). You can access child nodes in the AST using getChildren. Most of the important information about comment AST nodes is contained in the fields of the ParsedComment type.

This module is intended to be imported qualified.

Navigating the comment AST

getChildren :: ClangBase m => ParsedComment s' -> ClangT s m [ParsedComment s]

Returns the children nodes of the given comment in the comment AST.

Predicates and transformations

isWhitespace :: ClangBase m => ParsedComment s' -> ClangT s m Bool

Returns True if the provided comment is a TextComment which is empty or contains only whitespace, or if it is a ParagraphComment which contains only whitespace TextComment nodes.

hasTrailingNewline :: ClangBase m => ParsedComment s' -> ClangT s m Bool

Returns True if the provided comment is inline content and has a newline immediately following it in the comment text. Newlines between paragraphs do not count.

getTagCommentAsString :: ClangBase m => ParsedComment s' -> ClangT s m (Maybe (ClangString s))

Returns a string representation of an HTMLStartTagComment or HTMLEndTagComment. For other kinds of comments, returns Nothing.

getFullCommentAsHTML :: ClangBase m => ParsedComment s' -> ClangT s m (Maybe (ClangString s))

Converts the given FullComment 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 'brief' paragraph and equivalent commands;
• "para-returns" for 'returns' paragraph and equivalent commands;
• "word-returns" for the "Returns" word in a 'returns' paragraph.

Function argument documentation is rendered as a <dl> list with arguments sorted in function prototype order. The following CSS classes are 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. The following CSS classes are 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.

getFullCommentAsXML :: ClangBase m => ParsedComment s' -> ClangT s m (Maybe (ClangString s))

Converts the given FullComment to an XML document.

A Relax NG schema for the XML is distributed in the "comment-xml-schema.rng" file inside the libclang source tree.

Comment AST nodes

data ParsedComment s

A node in the comment AST.

Every constructor contains an opaque Comment value, which represents the AST node itself. The other fields are the user-visible metadata for that node type.

Constructors

TextComment (Comment s) (ClangString s)

Plain text. Inline content.

InlineCommandComment (Comment s) (ClangString s) InlineCommandRenderStyle [ClangString s]

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

HTMLStartTagComment (Comment s) (ClangString s) [(ClangString s, ClangString s)] Bool

An HTML start tag with attributes (represented as name/value pairs). Considered inline content. The final argument of the constructor is True if the tag is self-closing.

HTMLEndTagComment (Comment s) (ClangString s)

An HTML end tag. Considered inline content.

ParagraphComment (Comment s)

A paragraph, which contains inline content. The paragraph itself is block content.

BlockCommandComment (Comment s) (ClangString s) [ClangString s] (Maybe (ParsedComment s))

A command which has zero or more word-like arguments and a paragraph argument. Block content. The paragraph argument (of type ParsedComment) is also a child of the BlockCommandComment.

As an example, a '\brief' comment creates a BlockCommandComment AST node with no word-like arguments and a paragraph argument.

ParamCommandComment (Comment s) (ClangString s) (Maybe Int) ParamPassDirection

A '\param' or '\arg' command that describes a function parameter. The parameter name, index in the parameter list (or Nothing if the index is invalid), and parameter passing direction are provided as constructor fields. The description is provided as a child node.

TypeParamCommandComment (Comment s) (ClangString s) (Maybe [Int])

A '\tparam' command that describes a template parameter. The parameter name and position are provided as constructor fields, while the description is provided as a child node.

Since template parameters can be nested, the position is a list with a left-to-right position at each nesting depth. For example, for the following declaration:

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

The resulting position would be [0] for 'C', [1] for 'TT', and [1, 0] for 'T'.

VerbatimBlockCommandComment (Comment s) (Maybe (ParsedComment s))

A verbatim block command (e.g. preformatted code). A verbatim block has an opening and a closing command and contains multiple lines of text, represented as VerbatimBlockLineComment nodes.

VerbatimBlockLineComment (Comment s) (ClangString s)

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

VerbatimLineComment (Comment s) (ClangString s)

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

FullComment (Comment s)

A full comment attached to a declaration. Contains block content.

Instances

Eq (ParsedComment s)

Ord (ParsedComment s)

data ParamPassDirection

A parameter passing direction, either explicitly provided in the comment text or inferred.

Constructors

ExplicitParamPassDirection ParamPassDirectionKind

InferredParamPassDirection ParamPassDirectionKind

Instances

Eq ParamPassDirection

Ord ParamPassDirection

Read ParamPassDirection

Show ParamPassDirection

data ParamPassDirectionKind

A parameter passing direction.

Constructors

InParamPassDirection

OutParamPassDirection

InOutParamPassDirection

Instances

Bounded ParamPassDirectionKind

Enum ParamPassDirectionKind

Eq ParamPassDirectionKind

Ord ParamPassDirectionKind

Read ParamPassDirectionKind

Show ParamPassDirectionKind

data InlineCommandRenderStyle

A rendering style which should be used for the associated inline command in the comment AST.

Constructors

NormalInlineCommandRenderStyle

BoldInlineCommandRenderStyle

MonospacedInlineCommandRenderStyle

EmphasizedInlineCommandRenderStyle

Instances

Bounded InlineCommandRenderStyle

Enum InlineCommandRenderStyle

Eq InlineCommandRenderStyle

Ord InlineCommandRenderStyle

Read InlineCommandRenderStyle

Show InlineCommandRenderStyle