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