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;
39   CXTranslationUnit TranslationUnit;
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  */
47 CINDEX_LINKAGE CXComment clang_Cursor_getParsedComment(CXCursor C);
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  */
54 enum CXCommentKind {
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    */
59   CXComment_Null = 0,
60 
61   /**
62    * \brief Plain text.  Inline content.
63    */
64   CXComment_Text = 1,
65 
66   /**
67    * \brief A command with word-like arguments that is considered inline content.
68    *
69    * For example: \\c command.
70    */
71   CXComment_InlineCommand = 2,
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    */
82   CXComment_HTMLStartTag = 3,
83 
84   /**
85    * \brief HTML end tag.  Considered inline content.
86    *
87    * For example:
88    * \verbatim
89    * </a>
90    * \endverbatim
91    */
92   CXComment_HTMLEndTag = 4,
93 
94   /**
95    * \brief A paragraph, contains inline comment.  The paragraph itself is
96    * block content.
97    */
98   CXComment_Paragraph = 5,
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    */
112   CXComment_BlockCommand = 6,
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    */
120   CXComment_ParamCommand = 7,
121 
122   /**
123    * \brief A \\tparam command that describes a template parameter (name and
124    * description).
125    *
126    * For example: \\tparam T description.
127    */
128   CXComment_TParamCommand = 8,
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    */
140   CXComment_VerbatimBlockCommand = 9,
141 
142   /**
143    * \brief A line of text that is contained within a
144    * CXComment_VerbatimBlockCommand node.
145    */
146   CXComment_VerbatimBlockLine = 10,
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    */
153   CXComment_VerbatimLine = 11,
154 
155   /**
156    * \brief A full comment attached to a declaration, contains block content.
157    */
158   CXComment_FullComment = 12
159 };
160 
161 /**
162  * \brief The most appropriate rendering mode for an inline command, chosen on
163  * command semantics in Doxygen.
164  */
165 enum CXCommentInlineCommandRenderKind {
166   /**
167    * \brief Command argument should be rendered in a normal font.
168    */
169   CXCommentInlineCommandRenderKind_Normal,
170 
171   /**
172    * \brief Command argument should be rendered in a bold font.
173    */
174   CXCommentInlineCommandRenderKind_Bold,
175 
176   /**
177    * \brief Command argument should be rendered in a monospaced font.
178    */
179   CXCommentInlineCommandRenderKind_Monospaced,
180 
181   /**
182    * \brief Command argument should be rendered emphasized (typically italic
183    * font).
184    */
185   CXCommentInlineCommandRenderKind_Emphasized
186 };
187 
188 /**
189  * \brief Describes parameter passing direction for \\param or \\arg command.
190  */
191 enum CXCommentParamPassDirection {
192   /**
193    * \brief The parameter is an input parameter.
194    */
195   CXCommentParamPassDirection_In,
196 
197   /**
198    * \brief The parameter is an output parameter.
199    */
200   CXCommentParamPassDirection_Out,
201 
202   /**
203    * \brief The parameter is an input and output parameter.
204    */
205   CXCommentParamPassDirection_InOut
206 };
207 
208 /**
209  * \param Comment AST node of any kind.
210  *
211  * \returns the type of the AST node.
212  */
213 CINDEX_LINKAGE enum CXCommentKind clang_Comment_getKind(CXComment Comment);
214 
215 /**
216  * \param Comment AST node of any kind.
217  *
218  * \returns number of children of the AST node.
219  */
220 CINDEX_LINKAGE unsigned clang_Comment_getNumChildren(CXComment Comment);
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  */
229 CINDEX_LINKAGE
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  */
241 CINDEX_LINKAGE unsigned clang_Comment_isWhitespace(CXComment Comment);
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  */
248 CINDEX_LINKAGE
249 unsigned clang_InlineContentComment_hasTrailingNewline(CXComment Comment);
250 
251 /**
252  * \param Comment a \c CXComment_Text AST node.
253  *
254  * \returns text contained in the AST node.
255  */
256 CINDEX_LINKAGE CXString clang_TextComment_getText(CXComment Comment);
257 
258 /**
259  * \param Comment a \c CXComment_InlineCommand AST node.
260  *
261  * \returns name of the inline command.
262  */
263 CINDEX_LINKAGE
264 CXString clang_InlineCommandComment_getCommandName(CXComment Comment);
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  */
272 CINDEX_LINKAGE enum CXCommentInlineCommandRenderKind
273 clang_InlineCommandComment_getRenderKind(CXComment Comment);
274 
275 /**
276  * \param Comment a \c CXComment_InlineCommand AST node.
277  *
278  * \returns number of command arguments.
279  */
280 CINDEX_LINKAGE
281 unsigned clang_InlineCommandComment_getNumArgs(CXComment Comment);
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  */
290 CINDEX_LINKAGE
291 CXString clang_InlineCommandComment_getArgText(CXComment Comment,
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  */
300 CINDEX_LINKAGE CXString clang_HTMLTagComment_getTagName(CXComment Comment);
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  */
307 CINDEX_LINKAGE
308 unsigned clang_HTMLStartTagComment_isSelfClosing(CXComment Comment);
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  */
315 CINDEX_LINKAGE unsigned clang_HTMLStartTag_getNumAttrs(CXComment Comment);
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  */
324 CINDEX_LINKAGE
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  */
334 CINDEX_LINKAGE
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  */
342 CINDEX_LINKAGE
343 CXString clang_BlockCommandComment_getCommandName(CXComment Comment);
344 
345 /**
346  * \param Comment a \c CXComment_BlockCommand AST node.
347  *
348  * \returns number of word-like arguments.
349  */
350 CINDEX_LINKAGE
351 unsigned clang_BlockCommandComment_getNumArgs(CXComment Comment);
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  */
360 CINDEX_LINKAGE
361 CXString clang_BlockCommandComment_getArgText(CXComment Comment,
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  */
370 CINDEX_LINKAGE
371 CXComment clang_BlockCommandComment_getParagraph(CXComment Comment);
372 
373 /**
374  * \param Comment a \c CXComment_ParamCommand AST node.
375  *
376  * \returns parameter name.
377  */
378 CINDEX_LINKAGE
379 CXString clang_ParamCommandComment_getParamName(CXComment Comment);
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  */
388 CINDEX_LINKAGE
389 unsigned clang_ParamCommandComment_isParamIndexValid(CXComment Comment);
390 
391 /**
392  * \param Comment a \c CXComment_ParamCommand AST node.
393  *
394  * \returns zero-based parameter index in function prototype.
395  */
396 CINDEX_LINKAGE
397 unsigned clang_ParamCommandComment_getParamIndex(CXComment Comment);
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  */
405 CINDEX_LINKAGE
406 unsigned clang_ParamCommandComment_isDirectionExplicit(CXComment Comment);
407 
408 /**
409  * \param Comment a \c CXComment_ParamCommand AST node.
410  *
411  * \returns parameter passing direction.
412  */
413 CINDEX_LINKAGE
414 enum CXCommentParamPassDirection clang_ParamCommandComment_getDirection(
415                                                             CXComment Comment);
416 
417 /**
418  * \param Comment a \c CXComment_TParamCommand AST node.
419  *
420  * \returns template parameter name.
421  */
422 CINDEX_LINKAGE
423 CXString clang_TParamCommandComment_getParamName(CXComment Comment);
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  */
434 CINDEX_LINKAGE
435 unsigned clang_TParamCommandComment_isParamPositionValid(CXComment Comment);
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  */
450 CINDEX_LINKAGE
451 unsigned clang_TParamCommandComment_getDepth(CXComment Comment);
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  */
471 CINDEX_LINKAGE
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  */
479 CINDEX_LINKAGE
480 CXString clang_VerbatimBlockLineComment_getText(CXComment Comment);
481 
482 /**
483  * \param Comment a \c CXComment_VerbatimLine AST node.
484  *
485  * \returns text contained in the AST node.
486  */
487 CINDEX_LINKAGE CXString clang_VerbatimLineComment_getText(CXComment Comment);
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  */
497 CINDEX_LINKAGE CXString clang_HTMLTagComment_getAsString(CXComment Comment);
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  */
530 CINDEX_LINKAGE CXString clang_FullComment_getAsHTML(CXComment Comment);
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  */
542 CINDEX_LINKAGE CXString clang_FullComment_getAsXML(CXComment Comment);
543 
544 /**
545  * @}
546  */
547 
548 
549 #ifdef __cplusplus
550 }
551 #endif
552 
553 #endif /* CLANG_C_DOCUMENTATION_H */
554 
555