clang 17.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/CXErrorCode.h"
19#include "clang-c/ExternC.h"
20#include "clang-c/Index.h"
21
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;
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 */
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 */
55 /**
56 * 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 * Plain text. Inline content.
63 */
65
66 /**
67 * A command with word-like arguments that is considered inline content.
68 *
69 * For example: \\c command.
70 */
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 */
83
84 /**
85 * HTML end tag. Considered inline content.
86 *
87 * For example:
88 * \verbatim
89 * </a>
90 * \endverbatim
91 */
93
94 /**
95 * A paragraph, contains inline comment. The paragraph itself is
96 * block content.
97 */
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 */
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 */
121
122 /**
123 * A \\tparam command that describes a template parameter (name and
124 * description).
125 *
126 * For example: \\tparam T description.
127 */
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 */
141
142 /**
143 * A line of text that is contained within a
144 * CXComment_VerbatimBlockCommand node.
145 */
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 */
154
155 /**
156 * A full comment attached to a declaration, contains block content.
157 */
160
161/**
162 * The most appropriate rendering mode for an inline command, chosen on
163 * command semantics in Doxygen.
164 */
166 /**
167 * Command argument should be rendered in a normal font.
168 */
170
171 /**
172 * Command argument should be rendered in a bold font.
173 */
175
176 /**
177 * Command argument should be rendered in a monospaced font.
178 */
180
181 /**
182 * Command argument should be rendered emphasized (typically italic
183 * font).
184 */
186
187 /**
188 * Command argument should not be rendered (since it only defines an anchor).
189 */
192
193/**
194 * Describes parameter passing direction for \\param or \\arg command.
195 */
197 /**
198 * The parameter is an input parameter.
199 */
201
202 /**
203 * The parameter is an output parameter.
204 */
206
207 /**
208 * The parameter is an input and output parameter.
209 */
212
213/**
214 * \param Comment AST node of any kind.
215 *
216 * \returns the type of the AST node.
217 */
219
220/**
221 * \param Comment AST node of any kind.
222 *
223 * \returns number of children of the AST node.
224 */
226
227/**
228 * \param Comment AST node of any kind.
229 *
230 * \param ChildIdx child index (zero-based).
231 *
232 * \returns the specified child of the AST node.
233 */
235CXComment clang_Comment_getChild(CXComment Comment, unsigned ChildIdx);
236
237/**
238 * A \c CXComment_Paragraph node is considered whitespace if it contains
239 * only \c CXComment_Text nodes that are empty or whitespace.
240 *
241 * Other AST nodes (except \c CXComment_Paragraph and \c CXComment_Text) are
242 * never considered whitespace.
243 *
244 * \returns non-zero if \c Comment is whitespace.
245 */
247
248/**
249 * \returns non-zero if \c Comment is inline content and has a newline
250 * immediately following it in the comment text. Newlines between paragraphs
251 * do not count.
252 */
255
256/**
257 * \param Comment a \c CXComment_Text AST node.
258 *
259 * \returns text contained in the AST node.
260 */
262
263/**
264 * \param Comment a \c CXComment_InlineCommand AST node.
265 *
266 * \returns name of the inline command.
267 */
270
271/**
272 * \param Comment a \c CXComment_InlineCommand AST node.
273 *
274 * \returns the most appropriate rendering mode, chosen on command
275 * semantics in Doxygen.
276 */
279
280/**
281 * \param Comment a \c CXComment_InlineCommand AST node.
282 *
283 * \returns number of command arguments.
284 */
287
288/**
289 * \param Comment a \c CXComment_InlineCommand AST node.
290 *
291 * \param ArgIdx argument index (zero-based).
292 *
293 * \returns text of the specified argument.
294 */
297 unsigned ArgIdx);
298
299/**
300 * \param Comment a \c CXComment_HTMLStartTag or \c CXComment_HTMLEndTag AST
301 * node.
302 *
303 * \returns HTML tag name.
304 */
306
307/**
308 * \param Comment a \c CXComment_HTMLStartTag AST node.
309 *
310 * \returns non-zero if tag is self-closing (for example, &lt;br /&gt;).
311 */
314
315/**
316 * \param Comment a \c CXComment_HTMLStartTag AST node.
317 *
318 * \returns number of attributes (name-value pairs) attached to the start tag.
319 */
321
322/**
323 * \param Comment a \c CXComment_HTMLStartTag AST node.
324 *
325 * \param AttrIdx attribute index (zero-based).
326 *
327 * \returns name of the specified attribute.
328 */
331
332/**
333 * \param Comment a \c CXComment_HTMLStartTag AST node.
334 *
335 * \param AttrIdx attribute index (zero-based).
336 *
337 * \returns value of the specified attribute.
338 */
341
342/**
343 * \param Comment a \c CXComment_BlockCommand AST node.
344 *
345 * \returns name of the block command.
346 */
349
350/**
351 * \param Comment a \c CXComment_BlockCommand AST node.
352 *
353 * \returns number of word-like arguments.
354 */
357
358/**
359 * \param Comment a \c CXComment_BlockCommand AST node.
360 *
361 * \param ArgIdx argument index (zero-based).
362 *
363 * \returns text of the specified word-like argument.
364 */
367 unsigned ArgIdx);
368
369/**
370 * \param Comment a \c CXComment_BlockCommand or
371 * \c CXComment_VerbatimBlockCommand AST node.
372 *
373 * \returns paragraph argument of the block command.
374 */
377
378/**
379 * \param Comment a \c CXComment_ParamCommand AST node.
380 *
381 * \returns parameter name.
382 */
385
386/**
387 * \param Comment a \c CXComment_ParamCommand AST node.
388 *
389 * \returns non-zero if the parameter that this AST node represents was found
390 * in the function prototype and \c clang_ParamCommandComment_getParamIndex
391 * function will return a meaningful value.
392 */
395
396/**
397 * \param Comment a \c CXComment_ParamCommand AST node.
398 *
399 * \returns zero-based parameter index in function prototype.
400 */
403
404/**
405 * \param Comment a \c CXComment_ParamCommand AST node.
406 *
407 * \returns non-zero if parameter passing direction was specified explicitly in
408 * the comment.
409 */
412
413/**
414 * \param Comment a \c CXComment_ParamCommand AST node.
415 *
416 * \returns parameter passing direction.
417 */
420 CXComment Comment);
421
422/**
423 * \param Comment a \c CXComment_TParamCommand AST node.
424 *
425 * \returns template parameter name.
426 */
429
430/**
431 * \param Comment a \c CXComment_TParamCommand AST node.
432 *
433 * \returns non-zero if the parameter that this AST node represents was found
434 * in the template parameter list and
435 * \c clang_TParamCommandComment_getDepth and
436 * \c clang_TParamCommandComment_getIndex functions will return a meaningful
437 * value.
438 */
441
442/**
443 * \param Comment a \c CXComment_TParamCommand AST node.
444 *
445 * \returns zero-based nesting depth of this parameter in the template parameter list.
446 *
447 * For example,
448 * \verbatim
449 * template<typename C, template<typename T> class TT>
450 * void test(TT<int> aaa);
451 * \endverbatim
452 * for C and TT nesting depth is 0,
453 * for T nesting depth is 1.
454 */
457
458/**
459 * \param Comment a \c CXComment_TParamCommand AST node.
460 *
461 * \returns zero-based parameter index in the template parameter list at a
462 * given nesting depth.
463 *
464 * For example,
465 * \verbatim
466 * template<typename C, template<typename T> class TT>
467 * void test(TT<int> aaa);
468 * \endverbatim
469 * for C and TT nesting depth is 0, so we can ask for index at depth 0:
470 * at depth 0 C's index is 0, TT's index is 1.
471 *
472 * For T nesting depth is 1, so we can ask for index at depth 0 and 1:
473 * at depth 0 T's index is 1 (same as TT's),
474 * at depth 1 T's index is 0.
475 */
477unsigned clang_TParamCommandComment_getIndex(CXComment Comment, unsigned Depth);
478
479/**
480 * \param Comment a \c CXComment_VerbatimBlockLine AST node.
481 *
482 * \returns text contained in the AST node.
483 */
486
487/**
488 * \param Comment a \c CXComment_VerbatimLine AST node.
489 *
490 * \returns text contained in the AST node.
491 */
493
494/**
495 * Convert an HTML tag AST node to string.
496 *
497 * \param Comment a \c CXComment_HTMLStartTag or \c CXComment_HTMLEndTag AST
498 * node.
499 *
500 * \returns string containing an HTML tag.
501 */
503
504/**
505 * Convert a given full parsed comment to an HTML fragment.
506 *
507 * Specific details of HTML layout are subject to change. Don't try to parse
508 * this HTML back into an AST, use other APIs instead.
509 *
510 * Currently the following CSS classes are used:
511 * \li "para-brief" for \paragraph and equivalent commands;
512 * \li "para-returns" for \\returns paragraph and equivalent commands;
513 * \li "word-returns" for the "Returns" word in \\returns paragraph.
514 *
515 * Function argument documentation is rendered as a <dl> list with arguments
516 * sorted in function prototype order. CSS classes used:
517 * \li "param-name-index-NUMBER" for parameter name (<dt>);
518 * \li "param-descr-index-NUMBER" for parameter description (<dd>);
519 * \li "param-name-index-invalid" and "param-descr-index-invalid" are used if
520 * parameter index is invalid.
521 *
522 * Template parameter documentation is rendered as a <dl> list with
523 * parameters sorted in template parameter list order. CSS classes used:
524 * \li "tparam-name-index-NUMBER" for parameter name (<dt>);
525 * \li "tparam-descr-index-NUMBER" for parameter description (<dd>);
526 * \li "tparam-name-index-other" and "tparam-descr-index-other" are used for
527 * names inside template template parameters;
528 * \li "tparam-name-index-invalid" and "tparam-descr-index-invalid" are used if
529 * parameter position is invalid.
530 *
531 * \param Comment a \c CXComment_FullComment AST node.
532 *
533 * \returns string containing an HTML fragment.
534 */
536
537/**
538 * Convert a given full parsed comment to an XML document.
539 *
540 * A Relax NG schema for the XML can be found in comment-xml-schema.rng file
541 * inside clang source tree.
542 *
543 * \param Comment a \c CXComment_FullComment AST node.
544 *
545 * \returns string containing an XML document.
546 */
548
549/**
550 * CXAPISet is an opaque type that represents a data structure containing all
551 * the API information for a given translation unit. This can be used for a
552 * single symbol symbol graph for a given symbol.
553 */
554typedef struct CXAPISetImpl *CXAPISet;
555
556/**
557 * Traverses the translation unit to create a \c CXAPISet.
558 *
559 * \param tu is the \c CXTranslationUnit to build the \c CXAPISet for.
560 *
561 * \param out_api is a pointer to the output of this function. It is needs to be
562 * disposed of by calling clang_disposeAPISet.
563 *
564 * \returns Error code indicating success or failure of the APISet creation.
565 */
567 CXAPISet *out_api);
568
569/**
570 * Dispose of an APISet.
571 *
572 * The provided \c CXAPISet can not be used after this function is called.
573 */
575
576/**
577 * Generate a single symbol symbol graph for the given USR. Returns a null
578 * string if the associated symbol can not be found in the provided \c CXAPISet.
579 *
580 * The output contains the symbol graph as well as some additional information
581 * about related symbols.
582 *
583 * \param usr is a string containing the USR of the symbol to generate the
584 * symbol graph for.
585 *
586 * \param api the \c CXAPISet to look for the symbol in.
587 *
588 * \returns a string containing the serialized symbol graph representation for
589 * the symbol being queried or a null string if it can not be found in the
590 * APISet.
591 */
593 CXAPISet api);
594
595/**
596 * Generate a single symbol symbol graph for the declaration at the given
597 * cursor. Returns a null string if the AST node for the cursor isn't a
598 * declaration.
599 *
600 * The output contains the symbol graph as well as some additional information
601 * about related symbols.
602 *
603 * \param cursor the declaration for which to generate the single symbol symbol
604 * graph.
605 *
606 * \returns a string containing the serialized symbol graph representation for
607 * the symbol being queried or a null string if it can not be found in the
608 * APISet.
609 */
611
612/**
613 * @}
614 */
615
617
618#endif /* CLANG_C_DOCUMENTATION_H */
619
CXErrorCode
Error codes returned by libclang routines.
Definition: CXErrorCode.h:28
#define LLVM_CLANG_C_EXTERN_C_END
Definition: ExternC.h:36
#define LLVM_CLANG_C_EXTERN_C_BEGIN
Definition: ExternC.h:35
#define CINDEX_LINKAGE
Definition: Platform.h:38
CINDEX_LINKAGE CXString clang_TParamCommandComment_getParamName(CXComment Comment)
CINDEX_LINKAGE unsigned clang_HTMLStartTagComment_isSelfClosing(CXComment Comment)
CINDEX_LINKAGE unsigned clang_TParamCommandComment_getIndex(CXComment Comment, unsigned Depth)
CINDEX_LINKAGE unsigned clang_Comment_isWhitespace(CXComment Comment)
A CXComment_Paragraph node is considered whitespace if it contains only CXComment_Text nodes that are...
CINDEX_LINKAGE unsigned clang_TParamCommandComment_isParamPositionValid(CXComment Comment)
CXCommentInlineCommandRenderKind
The most appropriate rendering mode for an inline command, chosen on command semantics in Doxygen.
CXCommentKind
Describes the type of the comment AST node (CXComment).
Definition: Documentation.h:54
CINDEX_LINKAGE enum CXCommentInlineCommandRenderKind clang_InlineCommandComment_getRenderKind(CXComment Comment)
CINDEX_LINKAGE CXString clang_HTMLStartTag_getAttrName(CXComment Comment, unsigned AttrIdx)
CINDEX_LINKAGE CXString clang_VerbatimLineComment_getText(CXComment Comment)
CINDEX_LINKAGE CXString clang_HTMLTagComment_getTagName(CXComment Comment)
CINDEX_LINKAGE CXString clang_VerbatimBlockLineComment_getText(CXComment Comment)
CINDEX_LINKAGE CXString clang_getSymbolGraphForUSR(const char *usr, CXAPISet api)
Generate a single symbol symbol graph for the given USR.
CINDEX_LINKAGE enum CXErrorCode clang_createAPISet(CXTranslationUnit tu, CXAPISet *out_api)
Traverses the translation unit to create a CXAPISet.
CINDEX_LINKAGE CXString clang_InlineCommandComment_getArgText(CXComment Comment, unsigned ArgIdx)
CINDEX_LINKAGE CXString clang_HTMLTagComment_getAsString(CXComment Comment)
Convert an HTML tag AST node to string.
struct CXAPISetImpl * CXAPISet
CXAPISet is an opaque type that represents a data structure containing all the API information for a ...
CINDEX_LINKAGE CXString clang_InlineCommandComment_getCommandName(CXComment Comment)
CINDEX_LINKAGE unsigned clang_InlineCommandComment_getNumArgs(CXComment Comment)
CINDEX_LINKAGE unsigned clang_TParamCommandComment_getDepth(CXComment Comment)
CINDEX_LINKAGE CXString clang_BlockCommandComment_getCommandName(CXComment Comment)
CINDEX_LINKAGE unsigned clang_ParamCommandComment_isParamIndexValid(CXComment Comment)
CINDEX_LINKAGE CXString clang_BlockCommandComment_getArgText(CXComment Comment, unsigned ArgIdx)
CINDEX_LINKAGE unsigned clang_Comment_getNumChildren(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...
CINDEX_LINKAGE CXString clang_getSymbolGraphForCursor(CXCursor cursor)
Generate a single symbol symbol graph for the declaration at the given cursor.
CINDEX_LINKAGE CXComment clang_BlockCommandComment_getParagraph(CXComment Comment)
CINDEX_LINKAGE enum CXCommentParamPassDirection clang_ParamCommandComment_getDirection(CXComment Comment)
CINDEX_LINKAGE CXString clang_FullComment_getAsXML(CXComment Comment)
Convert a given full parsed comment to an XML document.
CINDEX_LINKAGE unsigned clang_BlockCommandComment_getNumArgs(CXComment Comment)
CINDEX_LINKAGE unsigned clang_InlineContentComment_hasTrailingNewline(CXComment Comment)
CINDEX_LINKAGE CXComment clang_Comment_getChild(CXComment Comment, unsigned ChildIdx)
CINDEX_LINKAGE enum CXCommentKind clang_Comment_getKind(CXComment Comment)
CINDEX_LINKAGE unsigned clang_ParamCommandComment_getParamIndex(CXComment Comment)
CINDEX_LINKAGE CXString clang_HTMLStartTag_getAttrValue(CXComment Comment, unsigned AttrIdx)
CINDEX_LINKAGE CXString clang_TextComment_getText(CXComment Comment)
CINDEX_LINKAGE void clang_disposeAPISet(CXAPISet api)
Dispose of an APISet.
CINDEX_LINKAGE unsigned clang_ParamCommandComment_isDirectionExplicit(CXComment Comment)
CXCommentParamPassDirection
Describes parameter passing direction for \param or \arg command.
CINDEX_LINKAGE CXString clang_FullComment_getAsHTML(CXComment Comment)
Convert a given full parsed comment to an HTML fragment.
CINDEX_LINKAGE unsigned clang_HTMLStartTag_getNumAttrs(CXComment Comment)
CINDEX_LINKAGE CXString clang_ParamCommandComment_getParamName(CXComment Comment)
@ CXCommentInlineCommandRenderKind_Emphasized
Command argument should be rendered emphasized (typically italic font).
@ CXCommentInlineCommandRenderKind_Monospaced
Command argument should be rendered in a monospaced font.
@ CXCommentInlineCommandRenderKind_Normal
Command argument should be rendered in a normal font.
@ CXCommentInlineCommandRenderKind_Bold
Command argument should be rendered in a bold font.
@ CXCommentInlineCommandRenderKind_Anchor
Command argument should not be rendered (since it only defines an anchor).
@ CXComment_Text
Plain text.
Definition: Documentation.h:64
@ CXComment_HTMLEndTag
HTML end tag.
Definition: Documentation.h:92
@ CXComment_Null
Null comment.
Definition: Documentation.h:59
@ CXComment_FullComment
A full comment attached to a declaration, contains block content.
@ CXComment_VerbatimBlockLine
A line of text that is contained within a CXComment_VerbatimBlockCommand node.
@ CXComment_ParamCommand
A \param or \arg command that describes the function parameter (name, passing direction,...
@ CXComment_Paragraph
A paragraph, contains inline comment.
Definition: Documentation.h:98
@ CXComment_TParamCommand
A \tparam command that describes a template parameter (name and description).
@ CXComment_BlockCommand
A command that has zero or more word-like arguments (number of word-like arguments depends on command...
@ CXComment_VerbatimBlockCommand
A verbatim block command (e.
@ CXComment_HTMLStartTag
HTML start tag with attributes (name-value pairs).
Definition: Documentation.h:82
@ CXComment_InlineCommand
A command with word-like arguments that is considered inline content.
Definition: Documentation.h:71
@ CXComment_VerbatimLine
A verbatim line command.
@ CXCommentParamPassDirection_Out
The parameter is an output parameter.
@ CXCommentParamPassDirection_InOut
The parameter is an input and output parameter.
@ CXCommentParamPassDirection_In
The parameter is an input parameter.
struct CXTranslationUnitImpl * CXTranslationUnit
A single translation unit, which resides in an index.
Definition: Index.h:87
A parsed comment.
Definition: Documentation.h:37
const void * ASTNode
Definition: Documentation.h:38
CXTranslationUnit TranslationUnit
Definition: Documentation.h:39
A cursor representing some element in the abstract syntax tree for a translation unit.
Definition: Index.h:2107
A character string.
Definition: CXString.h:37