Clang Project

clang_source_code/include/clang-c/Documentation.h
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/Index.h"
19
20#ifdef __cplusplus
21extern "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 * A parsed comment.
36 */
37typedef struct {
38  const void *ASTNode;
39  CXTranslationUnit TranslationUnit;
40} CXComment;
41
42/**
43 * 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 */
47CINDEX_LINKAGE CXComment clang_Cursor_getParsedComment(CXCursor C);
48
49/**
50 * 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 */
54enum CXCommentKind {
55  /**
56   * 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   * Plain text.  Inline content.
63   */
64  CXComment_Text = 1,
65
66  /**
67   * 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   * 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   * HTML end tag.  Considered inline content.
86   *
87   * For example:
88   * \verbatim
89   * </a>
90   * \endverbatim
91   */
92  CXComment_HTMLEndTag = 4,
93
94  /**
95   * A paragraph, contains inline comment.  The paragraph itself is
96   * block content.
97   */
98  CXComment_Paragraph = 5,
99
100  /**
101   * 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: \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   * 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   * 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   * 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   * A line of text that is contained within a
144   * CXComment_VerbatimBlockCommand node.
145   */
146  CXComment_VerbatimBlockLine = 10,
147
148  /**
149   * 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   * A full comment attached to a declaration, contains block content.
157   */
158  CXComment_FullComment = 12
159};
160
161/**
162 * The most appropriate rendering mode for an inline command, chosen on
163 * command semantics in Doxygen.
164 */
165enum CXCommentInlineCommandRenderKind {
166  /**
167   * Command argument should be rendered in a normal font.
168   */
169  CXCommentInlineCommandRenderKind_Normal,
170
171  /**
172   * Command argument should be rendered in a bold font.
173   */
174  CXCommentInlineCommandRenderKind_Bold,
175
176  /**
177   * Command argument should be rendered in a monospaced font.
178   */
179  CXCommentInlineCommandRenderKind_Monospaced,
180
181  /**
182   * Command argument should be rendered emphasized (typically italic
183   * font).
184   */
185  CXCommentInlineCommandRenderKind_Emphasized
186};
187
188/**
189 * Describes parameter passing direction for \\param or \\arg command.
190 */
191enum CXCommentParamPassDirection {
192  /**
193   * The parameter is an input parameter.
194   */
195  CXCommentParamPassDirection_In,
196
197  /**
198   * The parameter is an output parameter.
199   */
200  CXCommentParamPassDirection_Out,
201
202  /**
203   * 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 */
213CINDEX_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 */
220CINDEX_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 */
229CINDEX_LINKAGE
230CXComment clang_Comment_getChild(CXComment Comment, unsigned ChildIdx);
231
232/**
233 * 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 */
241CINDEX_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 */
248CINDEX_LINKAGE
249unsigned 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 */
256CINDEX_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 */
263CINDEX_LINKAGE
264CXString 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 */
272CINDEX_LINKAGE enum CXCommentInlineCommandRenderKind
273clang_InlineCommandComment_getRenderKind(CXComment Comment);
274
275/**
276 * \param Comment a \c CXComment_InlineCommand AST node.
277 *
278 * \returns number of command arguments.
279 */
280CINDEX_LINKAGE
281unsigned 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 */
290CINDEX_LINKAGE
291CXString 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 */
300CINDEX_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 */
307CINDEX_LINKAGE
308unsigned 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 */
315CINDEX_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 */
324CINDEX_LINKAGE
325CXString 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 */
334CINDEX_LINKAGE
335CXString 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 */
342CINDEX_LINKAGE
343CXString 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 */
350CINDEX_LINKAGE
351unsigned 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 */
360CINDEX_LINKAGE
361CXString 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 */
370CINDEX_LINKAGE
371CXComment clang_BlockCommandComment_getParagraph(CXComment Comment);
372
373/**
374 * \param Comment a \c CXComment_ParamCommand AST node.
375 *
376 * \returns parameter name.
377 */
378CINDEX_LINKAGE
379CXString 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 */
388CINDEX_LINKAGE
389unsigned 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 */
396CINDEX_LINKAGE
397unsigned 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 */
405CINDEX_LINKAGE
406unsigned clang_ParamCommandComment_isDirectionExplicit(CXComment Comment);
407
408/**
409 * \param Comment a \c CXComment_ParamCommand AST node.
410 *
411 * \returns parameter passing direction.
412 */
413CINDEX_LINKAGE
414enum 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 */
422CINDEX_LINKAGE
423CXString 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 */
434CINDEX_LINKAGE
435unsigned 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 */
450CINDEX_LINKAGE
451unsigned 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 */
471CINDEX_LINKAGE
472unsigned 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 */
479CINDEX_LINKAGE
480CXString 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 */
487CINDEX_LINKAGE CXString clang_VerbatimLineComment_getText(CXComment Comment);
488
489/**
490 * 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 */
497CINDEX_LINKAGE CXString clang_HTMLTagComment_getAsString(CXComment Comment);
498
499/**
500 * 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 \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 */
530CINDEX_LINKAGE CXString clang_FullComment_getAsHTML(CXComment Comment);
531
532/**
533 * 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 */
542CINDEX_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
(anonymous struct)::ASTNode
(anonymous struct)::TranslationUnit
CodeThinker, Enjoy your reading code