clang  14.0.0git
Documentation.h
Go to the documentation of this file.
1 /*==-- clang-c/Documentation.h - Utilities for comment processing -*- C -*-===*\
2 |* *|
3 |* Part of the LLVM Project, under the Apache License v2.0 with LLVM *|
4 |* Exceptions. *|
5 |* See https://llvm.org/LICENSE.txt for license information. *|
6 |* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception *|
7 |* *|
8 |*===----------------------------------------------------------------------===*|
9 |* *|
10 |* This header provides a supplementary interface for inspecting *|
11 |* documentation comments. *|
12 |* *|
13 \*===----------------------------------------------------------------------===*/
14 
15 #ifndef LLVM_CLANG_C_DOCUMENTATION_H
16 #define LLVM_CLANG_C_DOCUMENTATION_H
17 
18 #include "clang-c/ExternC.h"
19 #include "clang-c/Index.h"
20 
22 
23 /**
24  * \defgroup CINDEX_COMMENT Comment introspection
25  *
26  * The routines in this group provide access to information in documentation
27  * comments. These facilities are distinct from the core and may be subject to
28  * their own schedule of stability and deprecation.
29  *
30  * @{
31  */
32 
33 /**
34  * A parsed comment.
35  */
36 typedef struct {
37  const void *ASTNode;
39 } CXComment;
40 
41 /**
42  * Given a cursor that represents a documentable entity (e.g.,
43  * declaration), return the associated parsed comment as a
44  * \c CXComment_FullComment AST node.
45  */
47 
48 /**
49  * Describes the type of the comment AST node (\c CXComment). A comment
50  * node can be considered block content (e. g., paragraph), inline content
51  * (plain text) or neither (the root AST node).
52  */
54  /**
55  * Null comment. No AST node is constructed at the requested location
56  * because there is no text or a syntax error.
57  */
59 
60  /**
61  * Plain text. Inline content.
62  */
64 
65  /**
66  * A command with word-like arguments that is considered inline content.
67  *
68  * For example: \\c command.
69  */
71 
72  /**
73  * HTML start tag with attributes (name-value pairs). Considered
74  * inline content.
75  *
76  * For example:
77  * \verbatim
78  * <br> <br /> <a href="http://example.org/">
79  * \endverbatim
80  */
82 
83  /**
84  * HTML end tag. Considered inline content.
85  *
86  * For example:
87  * \verbatim
88  * </a>
89  * \endverbatim
90  */
92 
93  /**
94  * A paragraph, contains inline comment. The paragraph itself is
95  * block content.
96  */
98 
99  /**
100  * A command that has zero or more word-like arguments (number of
101  * word-like arguments depends on command name) and a paragraph as an
102  * argument. Block command is block content.
103  *
104  * Paragraph argument is also a child of the block command.
105  *
106  * For example: \has 0 word-like arguments and a paragraph argument.
107  *
108  * AST nodes of special kinds that parser knows about (e. g., \\param
109  * command) have their own node kinds.
110  */
112 
113  /**
114  * A \\param or \\arg command that describes the function parameter
115  * (name, passing direction, description).
116  *
117  * For example: \\param [in] ParamName description.
118  */
120 
121  /**
122  * A \\tparam command that describes a template parameter (name and
123  * description).
124  *
125  * For example: \\tparam T description.
126  */
128 
129  /**
130  * A verbatim block command (e. g., preformatted code). Verbatim
131  * block has an opening and a closing command and contains multiple lines of
132  * text (\c CXComment_VerbatimBlockLine child nodes).
133  *
134  * For example:
135  * \\verbatim
136  * aaa
137  * \\endverbatim
138  */
140 
141  /**
142  * A line of text that is contained within a
143  * CXComment_VerbatimBlockCommand node.
144  */
146 
147  /**
148  * A verbatim line command. Verbatim line has an opening command,
149  * a single line of text (up to the newline after the opening command) and
150  * has no closing command.
151  */
153 
154  /**
155  * A full comment attached to a declaration, contains block content.
156  */
158 };
159 
160 /**
161  * The most appropriate rendering mode for an inline command, chosen on
162  * command semantics in Doxygen.
163  */
165  /**
166  * Command argument should be rendered in a normal font.
167  */
169 
170  /**
171  * Command argument should be rendered in a bold font.
172  */
174 
175  /**
176  * Command argument should be rendered in a monospaced font.
177  */
179 
180  /**
181  * Command argument should be rendered emphasized (typically italic
182  * font).
183  */
185 
186  /**
187  * Command argument should not be rendered (since it only defines an anchor).
188  */
190 };
191 
192 /**
193  * Describes parameter passing direction for \\param or \\arg command.
194  */
196  /**
197  * The parameter is an input parameter.
198  */
200 
201  /**
202  * The parameter is an output parameter.
203  */
205 
206  /**
207  * The parameter is an input and output parameter.
208  */
210 };
211 
212 /**
213  * \param Comment AST node of any kind.
214  *
215  * \returns the type of the AST node.
216  */
218 
219 /**
220  * \param Comment AST node of any kind.
221  *
222  * \returns number of children of the AST node.
223  */
225 
226 /**
227  * \param Comment AST node of any kind.
228  *
229  * \param ChildIdx child index (zero-based).
230  *
231  * \returns the specified child of the AST node.
232  */
234 CXComment clang_Comment_getChild(CXComment Comment, unsigned ChildIdx);
235 
236 /**
237  * A \c CXComment_Paragraph node is considered whitespace if it contains
238  * only \c CXComment_Text nodes that are empty or whitespace.
239  *
240  * Other AST nodes (except \c CXComment_Paragraph and \c CXComment_Text) are
241  * never considered whitespace.
242  *
243  * \returns non-zero if \c Comment is whitespace.
244  */
246 
247 /**
248  * \returns non-zero if \c Comment is inline content and has a newline
249  * immediately following it in the comment text. Newlines between paragraphs
250  * do not count.
251  */
254 
255 /**
256  * \param Comment a \c CXComment_Text AST node.
257  *
258  * \returns text contained in the AST node.
259  */
261 
262 /**
263  * \param Comment a \c CXComment_InlineCommand AST node.
264  *
265  * \returns name of the inline command.
266  */
269 
270 /**
271  * \param Comment a \c CXComment_InlineCommand AST node.
272  *
273  * \returns the most appropriate rendering mode, chosen on command
274  * semantics in Doxygen.
275  */
278 
279 /**
280  * \param Comment a \c CXComment_InlineCommand AST node.
281  *
282  * \returns number of command arguments.
283  */
286 
287 /**
288  * \param Comment a \c CXComment_InlineCommand AST node.
289  *
290  * \param ArgIdx argument index (zero-based).
291  *
292  * \returns text of the specified argument.
293  */
296  unsigned ArgIdx);
297 
298 /**
299  * \param Comment a \c CXComment_HTMLStartTag or \c CXComment_HTMLEndTag AST
300  * node.
301  *
302  * \returns HTML tag name.
303  */
305 
306 /**
307  * \param Comment a \c CXComment_HTMLStartTag AST node.
308  *
309  * \returns non-zero if tag is self-closing (for example, &lt;br /&gt;).
310  */
313 
314 /**
315  * \param Comment a \c CXComment_HTMLStartTag AST node.
316  *
317  * \returns number of attributes (name-value pairs) attached to the start tag.
318  */
320 
321 /**
322  * \param Comment a \c CXComment_HTMLStartTag AST node.
323  *
324  * \param AttrIdx attribute index (zero-based).
325  *
326  * \returns name of the specified attribute.
327  */
329 CXString clang_HTMLStartTag_getAttrName(CXComment Comment, unsigned AttrIdx);
330 
331 /**
332  * \param Comment a \c CXComment_HTMLStartTag AST node.
333  *
334  * \param AttrIdx attribute index (zero-based).
335  *
336  * \returns value of the specified attribute.
337  */
339 CXString clang_HTMLStartTag_getAttrValue(CXComment Comment, unsigned AttrIdx);
340 
341 /**
342  * \param Comment a \c CXComment_BlockCommand AST node.
343  *
344  * \returns name of the block command.
345  */
348 
349 /**
350  * \param Comment a \c CXComment_BlockCommand AST node.
351  *
352  * \returns number of word-like arguments.
353  */
356 
357 /**
358  * \param Comment a \c CXComment_BlockCommand AST node.
359  *
360  * \param ArgIdx argument index (zero-based).
361  *
362  * \returns text of the specified word-like argument.
363  */
366  unsigned ArgIdx);
367 
368 /**
369  * \param Comment a \c CXComment_BlockCommand or
370  * \c CXComment_VerbatimBlockCommand AST node.
371  *
372  * \returns paragraph argument of the block command.
373  */
376 
377 /**
378  * \param Comment a \c CXComment_ParamCommand AST node.
379  *
380  * \returns parameter name.
381  */
384 
385 /**
386  * \param Comment a \c CXComment_ParamCommand AST node.
387  *
388  * \returns non-zero if the parameter that this AST node represents was found
389  * in the function prototype and \c clang_ParamCommandComment_getParamIndex
390  * function will return a meaningful value.
391  */
394 
395 /**
396  * \param Comment a \c CXComment_ParamCommand AST node.
397  *
398  * \returns zero-based parameter index in function prototype.
399  */
402 
403 /**
404  * \param Comment a \c CXComment_ParamCommand AST node.
405  *
406  * \returns non-zero if parameter passing direction was specified explicitly in
407  * the comment.
408  */
411 
412 /**
413  * \param Comment a \c CXComment_ParamCommand AST node.
414  *
415  * \returns parameter passing direction.
416  */
419  CXComment Comment);
420 
421 /**
422  * \param Comment a \c CXComment_TParamCommand AST node.
423  *
424  * \returns template parameter name.
425  */
428 
429 /**
430  * \param Comment a \c CXComment_TParamCommand AST node.
431  *
432  * \returns non-zero if the parameter that this AST node represents was found
433  * in the template parameter list and
434  * \c clang_TParamCommandComment_getDepth and
435  * \c clang_TParamCommandComment_getIndex functions will return a meaningful
436  * value.
437  */
440 
441 /**
442  * \param Comment a \c CXComment_TParamCommand AST node.
443  *
444  * \returns zero-based nesting depth of this parameter in the template parameter list.
445  *
446  * For example,
447  * \verbatim
448  * template<typename C, template<typename T> class TT>
449  * void test(TT<int> aaa);
450  * \endverbatim
451  * for C and TT nesting depth is 0,
452  * for T nesting depth is 1.
453  */
456 
457 /**
458  * \param Comment a \c CXComment_TParamCommand AST node.
459  *
460  * \returns zero-based parameter index in the template parameter list at a
461  * given nesting depth.
462  *
463  * For example,
464  * \verbatim
465  * template<typename C, template<typename T> class TT>
466  * void test(TT<int> aaa);
467  * \endverbatim
468  * for C and TT nesting depth is 0, so we can ask for index at depth 0:
469  * at depth 0 C's index is 0, TT's index is 1.
470  *
471  * For T nesting depth is 1, so we can ask for index at depth 0 and 1:
472  * at depth 0 T's index is 1 (same as TT's),
473  * at depth 1 T's index is 0.
474  */
476 unsigned clang_TParamCommandComment_getIndex(CXComment Comment, unsigned Depth);
477 
478 /**
479  * \param Comment a \c CXComment_VerbatimBlockLine AST node.
480  *
481  * \returns text contained in the AST node.
482  */
485 
486 /**
487  * \param Comment a \c CXComment_VerbatimLine AST node.
488  *
489  * \returns text contained in the AST node.
490  */
492 
493 /**
494  * Convert an HTML tag AST node to string.
495  *
496  * \param Comment a \c CXComment_HTMLStartTag or \c CXComment_HTMLEndTag AST
497  * node.
498  *
499  * \returns string containing an HTML tag.
500  */
502 
503 /**
504  * Convert a given full parsed comment to an HTML fragment.
505  *
506  * Specific details of HTML layout are subject to change. Don't try to parse
507  * this HTML back into an AST, use other APIs instead.
508  *
509  * Currently the following CSS classes are used:
510  * \li "para-brief" for \paragraph and equivalent commands;
511  * \li "para-returns" for \\returns paragraph and equivalent commands;
512  * \li "word-returns" for the "Returns" word in \\returns paragraph.
513  *
514  * Function argument documentation is rendered as a <dl> list with arguments
515  * sorted in function prototype order. CSS classes used:
516  * \li "param-name-index-NUMBER" for parameter name (<dt>);
517  * \li "param-descr-index-NUMBER" for parameter description (<dd>);
518  * \li "param-name-index-invalid" and "param-descr-index-invalid" are used if
519  * parameter index is invalid.
520  *
521  * Template parameter documentation is rendered as a <dl> list with
522  * parameters sorted in template parameter list order. CSS classes used:
523  * \li "tparam-name-index-NUMBER" for parameter name (<dt>);
524  * \li "tparam-descr-index-NUMBER" for parameter description (<dd>);
525  * \li "tparam-name-index-other" and "tparam-descr-index-other" are used for
526  * names inside template template parameters;
527  * \li "tparam-name-index-invalid" and "tparam-descr-index-invalid" are used if
528  * parameter position is invalid.
529  *
530  * \param Comment a \c CXComment_FullComment AST node.
531  *
532  * \returns string containing an HTML fragment.
533  */
535 
536 /**
537  * Convert a given full parsed comment to an XML document.
538  *
539  * A Relax NG schema for the XML can be found in comment-xml-schema.rng file
540  * inside clang source tree.
541  *
542  * \param Comment a \c CXComment_FullComment AST node.
543  *
544  * \returns string containing an XML document.
545  */
547 
548 /**
549  * @}
550  */
551 
553 
554 #endif /* CLANG_C_DOCUMENTATION_H */
555 
clang_HTMLStartTag_getAttrValue
CINDEX_LINKAGE CXString clang_HTMLStartTag_getAttrValue(CXComment Comment, unsigned AttrIdx)
CXComment_HTMLEndTag
@ CXComment_HTMLEndTag
HTML end tag.
Definition: Documentation.h:91
LLVM_CLANG_C_EXTERN_C_END
#define LLVM_CLANG_C_EXTERN_C_END
Definition: ExternC.h:36
CXCommentInlineCommandRenderKind_Monospaced
@ CXCommentInlineCommandRenderKind_Monospaced
Command argument should be rendered in a monospaced font.
Definition: Documentation.h:178
CXTranslationUnit
struct CXTranslationUnitImpl * CXTranslationUnit
A single translation unit, which resides in an index.
Definition: Index.h:86
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...
CXCommentInlineCommandRenderKind
CXCommentInlineCommandRenderKind
The most appropriate rendering mode for an inline command, chosen on command semantics in Doxygen.
Definition: Documentation.h:164
CXComment_Paragraph
@ CXComment_Paragraph
A paragraph, contains inline comment.
Definition: Documentation.h:97
clang_HTMLTagComment_getAsString
CINDEX_LINKAGE CXString clang_HTMLTagComment_getAsString(CXComment Comment)
Convert an HTML tag AST node to string.
AttributeLangSupport::C
@ C
Definition: SemaDeclAttr.cpp:54
Index.h
CXComment_BlockCommand
@ CXComment_BlockCommand
A command that has zero or more word-like arguments (number of word-like arguments depends on command...
Definition: Documentation.h:111
CXComment_TParamCommand
@ CXComment_TParamCommand
A \tparam command that describes a template parameter (name and description).
Definition: Documentation.h:127
CXComment_Null
@ CXComment_Null
Null comment.
Definition: Documentation.h:58
CXComment_VerbatimBlockCommand
@ CXComment_VerbatimBlockCommand
A verbatim block command (e.
Definition: Documentation.h:139
CXCommentInlineCommandRenderKind_Anchor
@ CXCommentInlineCommandRenderKind_Anchor
Command argument should not be rendered (since it only defines an anchor).
Definition: Documentation.h:189
clang_BlockCommandComment_getParagraph
CINDEX_LINKAGE CXComment clang_BlockCommandComment_getParagraph(CXComment Comment)
LLVM_CLANG_C_EXTERN_C_BEGIN
#define LLVM_CLANG_C_EXTERN_C_BEGIN
Definition: ExternC.h:35
clang_TParamCommandComment_getParamName
CINDEX_LINKAGE CXString clang_TParamCommandComment_getParamName(CXComment Comment)
clang_ParamCommandComment_getParamName
CINDEX_LINKAGE CXString clang_ParamCommandComment_getParamName(CXComment Comment)
clang_ParamCommandComment_getDirection
CINDEX_LINKAGE enum CXCommentParamPassDirection clang_ParamCommandComment_getDirection(CXComment Comment)
CXComment::TranslationUnit
CXTranslationUnit TranslationUnit
Definition: Documentation.h:38
CXCommentInlineCommandRenderKind_Bold
@ CXCommentInlineCommandRenderKind_Bold
Command argument should be rendered in a bold font.
Definition: Documentation.h:173
CXCommentKind
CXCommentKind
Describes the type of the comment AST node (CXComment).
Definition: Documentation.h:53
clang_VerbatimLineComment_getText
CINDEX_LINKAGE CXString clang_VerbatimLineComment_getText(CXComment Comment)
clang_InlineCommandComment_getNumArgs
CINDEX_LINKAGE unsigned clang_InlineCommandComment_getNumArgs(CXComment Comment)
CXComment_InlineCommand
@ CXComment_InlineCommand
A command with word-like arguments that is considered inline content.
Definition: Documentation.h:70
Depth
int Depth
Definition: ASTDiff.cpp:191
CXComment_Text
@ CXComment_Text
Plain text.
Definition: Documentation.h:63
clang_InlineCommandComment_getCommandName
CINDEX_LINKAGE CXString clang_InlineCommandComment_getCommandName(CXComment Comment)
clang_TParamCommandComment_isParamPositionValid
CINDEX_LINKAGE unsigned clang_TParamCommandComment_isParamPositionValid(CXComment Comment)
clang_TParamCommandComment_getDepth
CINDEX_LINKAGE unsigned clang_TParamCommandComment_getDepth(CXComment Comment)
clang_HTMLTagComment_getTagName
CINDEX_LINKAGE CXString clang_HTMLTagComment_getTagName(CXComment Comment)
clang_VerbatimBlockLineComment_getText
CINDEX_LINKAGE CXString clang_VerbatimBlockLineComment_getText(CXComment Comment)
CXCommentParamPassDirection
CXCommentParamPassDirection
Describes parameter passing direction for \param or \arg command.
Definition: Documentation.h:195
CXComment_VerbatimBlockLine
@ CXComment_VerbatimBlockLine
A line of text that is contained within a CXComment_VerbatimBlockCommand node.
Definition: Documentation.h:145
CXCommentParamPassDirection_InOut
@ CXCommentParamPassDirection_InOut
The parameter is an input and output parameter.
Definition: Documentation.h:209
clang_BlockCommandComment_getNumArgs
CINDEX_LINKAGE unsigned clang_BlockCommandComment_getNumArgs(CXComment Comment)
clang_FullComment_getAsHTML
CINDEX_LINKAGE CXString clang_FullComment_getAsHTML(CXComment Comment)
Convert a given full parsed comment to an HTML fragment.
CXCommentInlineCommandRenderKind_Normal
@ CXCommentInlineCommandRenderKind_Normal
Command argument should be rendered in a normal font.
Definition: Documentation.h:168
CXComment::ASTNode
const void * ASTNode
Definition: Documentation.h:37
clang_HTMLStartTag_getNumAttrs
CINDEX_LINKAGE unsigned clang_HTMLStartTag_getNumAttrs(CXComment Comment)
CXComment_HTMLStartTag
@ CXComment_HTMLStartTag
HTML start tag with attributes (name-value pairs).
Definition: Documentation.h:81
clang_HTMLStartTag_getAttrName
CINDEX_LINKAGE CXString clang_HTMLStartTag_getAttrName(CXComment Comment, unsigned AttrIdx)
clang_TextComment_getText
CINDEX_LINKAGE CXString clang_TextComment_getText(CXComment Comment)
CINDEX_LINKAGE
#define CINDEX_LINKAGE
Definition: Platform.h:38
CXComment
A parsed comment.
Definition: Documentation.h:36
CXCommentParamPassDirection_In
@ CXCommentParamPassDirection_In
The parameter is an input parameter.
Definition: Documentation.h:199
CXCommentInlineCommandRenderKind_Emphasized
@ CXCommentInlineCommandRenderKind_Emphasized
Command argument should be rendered emphasized (typically italic font).
Definition: Documentation.h:184
clang_FullComment_getAsXML
CINDEX_LINKAGE CXString clang_FullComment_getAsXML(CXComment Comment)
Convert a given full parsed comment to an XML document.
clang_ParamCommandComment_getParamIndex
CINDEX_LINKAGE unsigned clang_ParamCommandComment_getParamIndex(CXComment Comment)
clang_TParamCommandComment_getIndex
CINDEX_LINKAGE unsigned clang_TParamCommandComment_getIndex(CXComment Comment, unsigned Depth)
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 parse...
clang_BlockCommandComment_getCommandName
CINDEX_LINKAGE CXString clang_BlockCommandComment_getCommandName(CXComment Comment)
CXString
A character string.
Definition: CXString.h:37
CXCommentParamPassDirection_Out
@ CXCommentParamPassDirection_Out
The parameter is an output parameter.
Definition: Documentation.h:204
clang_Comment_getNumChildren
CINDEX_LINKAGE unsigned clang_Comment_getNumChildren(CXComment Comment)
clang_HTMLStartTagComment_isSelfClosing
CINDEX_LINKAGE unsigned clang_HTMLStartTagComment_isSelfClosing(CXComment Comment)
clang_Comment_getKind
CINDEX_LINKAGE enum CXCommentKind clang_Comment_getKind(CXComment Comment)
CXComment_VerbatimLine
@ CXComment_VerbatimLine
A verbatim line command.
Definition: Documentation.h:152
clang_InlineCommandComment_getRenderKind
CINDEX_LINKAGE enum CXCommentInlineCommandRenderKind clang_InlineCommandComment_getRenderKind(CXComment Comment)
clang_InlineCommandComment_getArgText
CINDEX_LINKAGE CXString clang_InlineCommandComment_getArgText(CXComment Comment, unsigned ArgIdx)
clang_InlineContentComment_hasTrailingNewline
CINDEX_LINKAGE unsigned clang_InlineContentComment_hasTrailingNewline(CXComment Comment)
clang_ParamCommandComment_isDirectionExplicit
CINDEX_LINKAGE unsigned clang_ParamCommandComment_isDirectionExplicit(CXComment Comment)
clang_BlockCommandComment_getArgText
CINDEX_LINKAGE CXString clang_BlockCommandComment_getArgText(CXComment Comment, unsigned ArgIdx)
clang_ParamCommandComment_isParamIndexValid
CINDEX_LINKAGE unsigned clang_ParamCommandComment_isParamIndexValid(CXComment Comment)
CXComment_ParamCommand
@ CXComment_ParamCommand
A \param or \arg command that describes the function parameter (name, passing direction,...
Definition: Documentation.h:119
clang_Comment_getChild
CINDEX_LINKAGE CXComment clang_Comment_getChild(CXComment Comment, unsigned ChildIdx)
ExternC.h
CXComment_FullComment
@ CXComment_FullComment
A full comment attached to a declaration, contains block content.
Definition: Documentation.h:157
CXCursor
A cursor representing some element in the abstract syntax tree for a translation unit.
Definition: Index.h:2710