620 lines · c
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_H16#define LLVM_CLANG_C_DOCUMENTATION_H17 18#include "clang-c/CXErrorCode.h"19#include "clang-c/ExternC.h"20#include "clang-c/Index.h"21 22LLVM_CLANG_C_EXTERN_C_BEGIN23 24/**25 * \defgroup CINDEX_COMMENT Comment introspection26 *27 * The routines in this group provide access to information in documentation28 * comments. These facilities are distinct from the core and may be subject to29 * 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 a45 * \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 comment51 * node can be considered block content (e. g., paragraph), inline content52 * (plain text) or neither (the root AST node).53 */54enum CXCommentKind {55 /**56 * Null comment. No AST node is constructed at the requested location57 * 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). Considered75 * inline content.76 *77 * For example:78 * \verbatim79 * <br> <br /> <a href="http://example.org/">80 * \endverbatim81 */82 CXComment_HTMLStartTag = 3,83 84 /**85 * HTML end tag. Considered inline content.86 *87 * For example:88 * \verbatim89 * </a>90 * \endverbatim91 */92 CXComment_HTMLEndTag = 4,93 94 /**95 * A paragraph, contains inline comment. The paragraph itself is96 * block content.97 */98 CXComment_Paragraph = 5,99 100 /**101 * A command that has zero or more word-like arguments (number of102 * word-like arguments depends on command name) and a paragraph as an103 * 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., \\param110 * command) have their own node kinds.111 */112 CXComment_BlockCommand = 6,113 114 /**115 * A \\param or \\arg command that describes the function parameter116 * (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 and124 * description).125 *126 * For example: \\tparam T description.127 */128 CXComment_TParamCommand = 8,129 130 /**131 * A verbatim block command (e. g., preformatted code). Verbatim132 * block has an opening and a closing command and contains multiple lines of133 * text (\c CXComment_VerbatimBlockLine child nodes).134 *135 * For example:136 * \\verbatim137 * aaa138 * \\endverbatim139 */140 CXComment_VerbatimBlockCommand = 9,141 142 /**143 * A line of text that is contained within a144 * 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) and151 * 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 = 12159};160 161/**162 * The most appropriate rendering mode for an inline command, chosen on163 * 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 italic183 * font).184 */185 CXCommentInlineCommandRenderKind_Emphasized,186 187 /**188 * Command argument should not be rendered (since it only defines an anchor).189 */190 CXCommentInlineCommandRenderKind_Anchor191};192 193/**194 * Describes parameter passing direction for \\param or \\arg command.195 */196enum CXCommentParamPassDirection {197 /**198 * The parameter is an input parameter.199 */200 CXCommentParamPassDirection_In,201 202 /**203 * The parameter is an output parameter.204 */205 CXCommentParamPassDirection_Out,206 207 /**208 * The parameter is an input and output parameter.209 */210 CXCommentParamPassDirection_InOut211};212 213/**214 * \param Comment AST node of any kind.215 *216 * \returns the type of the AST node.217 */218CINDEX_LINKAGE enum CXCommentKind clang_Comment_getKind(CXComment Comment);219 220/**221 * \param Comment AST node of any kind.222 *223 * \returns number of children of the AST node.224 */225CINDEX_LINKAGE unsigned clang_Comment_getNumChildren(CXComment Comment);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 */234CINDEX_LINKAGE235CXComment clang_Comment_getChild(CXComment Comment, unsigned ChildIdx);236 237/**238 * A \c CXComment_Paragraph node is considered whitespace if it contains239 * only \c CXComment_Text nodes that are empty or whitespace.240 *241 * Other AST nodes (except \c CXComment_Paragraph and \c CXComment_Text) are242 * never considered whitespace.243 *244 * \returns non-zero if \c Comment is whitespace.245 */246CINDEX_LINKAGE unsigned clang_Comment_isWhitespace(CXComment Comment);247 248/**249 * \returns non-zero if \c Comment is inline content and has a newline250 * immediately following it in the comment text. Newlines between paragraphs251 * do not count.252 */253CINDEX_LINKAGE254unsigned clang_InlineContentComment_hasTrailingNewline(CXComment Comment);255 256/**257 * \param Comment a \c CXComment_Text AST node.258 *259 * \returns text contained in the AST node.260 */261CINDEX_LINKAGE CXString clang_TextComment_getText(CXComment Comment);262 263/**264 * \param Comment a \c CXComment_InlineCommand AST node.265 *266 * \returns name of the inline command.267 */268CINDEX_LINKAGE269CXString clang_InlineCommandComment_getCommandName(CXComment Comment);270 271/**272 * \param Comment a \c CXComment_InlineCommand AST node.273 *274 * \returns the most appropriate rendering mode, chosen on command275 * semantics in Doxygen.276 */277CINDEX_LINKAGE enum CXCommentInlineCommandRenderKind278clang_InlineCommandComment_getRenderKind(CXComment Comment);279 280/**281 * \param Comment a \c CXComment_InlineCommand AST node.282 *283 * \returns number of command arguments.284 */285CINDEX_LINKAGE286unsigned clang_InlineCommandComment_getNumArgs(CXComment Comment);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 */295CINDEX_LINKAGE296CXString clang_InlineCommandComment_getArgText(CXComment Comment,297 unsigned ArgIdx);298 299/**300 * \param Comment a \c CXComment_HTMLStartTag or \c CXComment_HTMLEndTag AST301 * node.302 *303 * \returns HTML tag name.304 */305CINDEX_LINKAGE CXString clang_HTMLTagComment_getTagName(CXComment Comment);306 307/**308 * \param Comment a \c CXComment_HTMLStartTag AST node.309 *310 * \returns non-zero if tag is self-closing (for example, <br />).311 */312CINDEX_LINKAGE313unsigned clang_HTMLStartTagComment_isSelfClosing(CXComment Comment);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 */320CINDEX_LINKAGE unsigned clang_HTMLStartTag_getNumAttrs(CXComment Comment);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 */329CINDEX_LINKAGE330CXString clang_HTMLStartTag_getAttrName(CXComment Comment, unsigned AttrIdx);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 */339CINDEX_LINKAGE340CXString clang_HTMLStartTag_getAttrValue(CXComment Comment, unsigned AttrIdx);341 342/**343 * \param Comment a \c CXComment_BlockCommand AST node.344 *345 * \returns name of the block command.346 */347CINDEX_LINKAGE348CXString clang_BlockCommandComment_getCommandName(CXComment Comment);349 350/**351 * \param Comment a \c CXComment_BlockCommand AST node.352 *353 * \returns number of word-like arguments.354 */355CINDEX_LINKAGE356unsigned clang_BlockCommandComment_getNumArgs(CXComment Comment);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 */365CINDEX_LINKAGE366CXString clang_BlockCommandComment_getArgText(CXComment Comment,367 unsigned ArgIdx);368 369/**370 * \param Comment a \c CXComment_BlockCommand or371 * \c CXComment_VerbatimBlockCommand AST node.372 *373 * \returns paragraph argument of the block command.374 */375CINDEX_LINKAGE376CXComment clang_BlockCommandComment_getParagraph(CXComment Comment);377 378/**379 * \param Comment a \c CXComment_ParamCommand AST node.380 *381 * \returns parameter name.382 */383CINDEX_LINKAGE384CXString clang_ParamCommandComment_getParamName(CXComment Comment);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 found390 * in the function prototype and \c clang_ParamCommandComment_getParamIndex391 * function will return a meaningful value.392 */393CINDEX_LINKAGE394unsigned clang_ParamCommandComment_isParamIndexValid(CXComment Comment);395 396/**397 * \param Comment a \c CXComment_ParamCommand AST node.398 *399 * \returns zero-based parameter index in function prototype.400 */401CINDEX_LINKAGE402unsigned clang_ParamCommandComment_getParamIndex(CXComment Comment);403 404/**405 * \param Comment a \c CXComment_ParamCommand AST node.406 *407 * \returns non-zero if parameter passing direction was specified explicitly in408 * the comment.409 */410CINDEX_LINKAGE411unsigned clang_ParamCommandComment_isDirectionExplicit(CXComment Comment);412 413/**414 * \param Comment a \c CXComment_ParamCommand AST node.415 *416 * \returns parameter passing direction.417 */418CINDEX_LINKAGE419enum CXCommentParamPassDirection clang_ParamCommandComment_getDirection(420 CXComment Comment);421 422/**423 * \param Comment a \c CXComment_TParamCommand AST node.424 *425 * \returns template parameter name.426 */427CINDEX_LINKAGE428CXString clang_TParamCommandComment_getParamName(CXComment Comment);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 found434 * in the template parameter list and435 * \c clang_TParamCommandComment_getDepth and436 * \c clang_TParamCommandComment_getIndex functions will return a meaningful437 * value.438 */439CINDEX_LINKAGE440unsigned clang_TParamCommandComment_isParamPositionValid(CXComment Comment);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 * \verbatim449 * template<typename C, template<typename T> class TT>450 * void test(TT<int> aaa);451 * \endverbatim452 * for C and TT nesting depth is 0,453 * for T nesting depth is 1.454 */455CINDEX_LINKAGE456unsigned clang_TParamCommandComment_getDepth(CXComment Comment);457 458/**459 * \param Comment a \c CXComment_TParamCommand AST node.460 *461 * \returns zero-based parameter index in the template parameter list at a462 * given nesting depth.463 *464 * For example,465 * \verbatim466 * template<typename C, template<typename T> class TT>467 * void test(TT<int> aaa);468 * \endverbatim469 * 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 */476CINDEX_LINKAGE477unsigned 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 */484CINDEX_LINKAGE485CXString clang_VerbatimBlockLineComment_getText(CXComment Comment);486 487/**488 * \param Comment a \c CXComment_VerbatimLine AST node.489 *490 * \returns text contained in the AST node.491 */492CINDEX_LINKAGE CXString clang_VerbatimLineComment_getText(CXComment Comment);493 494/**495 * Convert an HTML tag AST node to string.496 *497 * \param Comment a \c CXComment_HTMLStartTag or \c CXComment_HTMLEndTag AST498 * node.499 *500 * \returns string containing an HTML tag.501 */502CINDEX_LINKAGE CXString clang_HTMLTagComment_getAsString(CXComment Comment);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 parse508 * 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 arguments516 * 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 if520 * parameter index is invalid.521 *522 * Template parameter documentation is rendered as a \<dl\> list with523 * 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 for527 * names inside template template parameters;528 * \li "tparam-name-index-invalid" and "tparam-descr-index-invalid" are used if529 * parameter position is invalid.530 *531 * \param Comment a \c CXComment_FullComment AST node.532 *533 * \returns string containing an HTML fragment.534 */535CINDEX_LINKAGE CXString clang_FullComment_getAsHTML(CXComment Comment);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 file541 * inside clang source tree.542 *543 * \param Comment a \c CXComment_FullComment AST node.544 *545 * \returns string containing an XML document.546 */547CINDEX_LINKAGE CXString clang_FullComment_getAsXML(CXComment Comment);548 549/**550 * CXAPISet is an opaque type that represents a data structure containing all551 * the API information for a given translation unit. This can be used for a552 * 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 be562 * disposed of by calling clang_disposeAPISet.563 *564 * \returns Error code indicating success or failure of the APISet creation.565 */566CINDEX_LINKAGE enum CXErrorCode clang_createAPISet(CXTranslationUnit tu,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 */574CINDEX_LINKAGE void clang_disposeAPISet(CXAPISet api);575 576/**577 * Generate a single symbol symbol graph for the given USR. Returns a null578 * 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 information581 * about related symbols.582 *583 * \param usr is a string containing the USR of the symbol to generate the584 * 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 for589 * the symbol being queried or a null string if it can not be found in the590 * APISet.591 */592CINDEX_LINKAGE CXString clang_getSymbolGraphForUSR(const char *usr,593 CXAPISet api);594 595/**596 * Generate a single symbol symbol graph for the declaration at the given597 * cursor. Returns a null string if the AST node for the cursor isn't a598 * declaration.599 *600 * The output contains the symbol graph as well as some additional information601 * about related symbols.602 *603 * \param cursor the declaration for which to generate the single symbol symbol604 * graph.605 *606 * \returns a string containing the serialized symbol graph representation for607 * the symbol being queried or a null string if it can not be found in the608 * APISet.609 */610CINDEX_LINKAGE CXString clang_getSymbolGraphForCursor(CXCursor cursor);611 612/**613 * @}614 */615 616LLVM_CLANG_C_EXTERN_C_END617 618#endif /* CLANG_C_DOCUMENTATION_H */619 620