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 22 LLVM_CLANG_C_EXTERN_C_BEGIN 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 */ 37 typedef 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 */ 47 CINDEX_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 */ 54 enum 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 */ 165 enum 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 * Command argument should not be rendered (since it only defines an anchor). 189 */ 190 CXCommentInlineCommandRenderKind_Anchor 191 }; 192 193 /** 194 * Describes parameter passing direction for \\param or \\arg command. 195 */ 196 enum 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_InOut 211 }; 212 213 /** 214 * \param Comment AST node of any kind. 215 * 216 * \returns the type of the AST node. 217 */ 218 CINDEX_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 */ 225 CINDEX_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 */ 234 CINDEX_LINKAGE 235 CXComment 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 */ 246 CINDEX_LINKAGE unsigned clang_Comment_isWhitespace(CXComment Comment); 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 */ 253 CINDEX_LINKAGE 254 unsigned 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 */ 261 CINDEX_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 */ 268 CINDEX_LINKAGE 269 CXString 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 command 275 * semantics in Doxygen. 276 */ 277 CINDEX_LINKAGE enum CXCommentInlineCommandRenderKind 278 clang_InlineCommandComment_getRenderKind(CXComment Comment); 279 280 /** 281 * \param Comment a \c CXComment_InlineCommand AST node. 282 * 283 * \returns number of command arguments. 284 */ 285 CINDEX_LINKAGE 286 unsigned 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 */ 295 CINDEX_LINKAGE 296 CXString clang_InlineCommandComment_getArgText(CXComment Comment, 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 */ 305 CINDEX_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 */ 312 CINDEX_LINKAGE 313 unsigned 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 */ 320 CINDEX_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 */ 329 CINDEX_LINKAGE 330 CXString 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 */ 339 CINDEX_LINKAGE 340 CXString 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 */ 347 CINDEX_LINKAGE 348 CXString 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 */ 355 CINDEX_LINKAGE 356 unsigned 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 */ 365 CINDEX_LINKAGE 366 CXString clang_BlockCommandComment_getArgText(CXComment Comment, 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 */ 375 CINDEX_LINKAGE 376 CXComment clang_BlockCommandComment_getParagraph(CXComment Comment); 377 378 /** 379 * \param Comment a \c CXComment_ParamCommand AST node. 380 * 381 * \returns parameter name. 382 */ 383 CINDEX_LINKAGE 384 CXString 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 found 390 * in the function prototype and \c clang_ParamCommandComment_getParamIndex 391 * function will return a meaningful value. 392 */ 393 CINDEX_LINKAGE 394 unsigned 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 */ 401 CINDEX_LINKAGE 402 unsigned 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 in 408 * the comment. 409 */ 410 CINDEX_LINKAGE 411 unsigned clang_ParamCommandComment_isDirectionExplicit(CXComment Comment); 412 413 /** 414 * \param Comment a \c CXComment_ParamCommand AST node. 415 * 416 * \returns parameter passing direction. 417 */ 418 CINDEX_LINKAGE 419 enum 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 */ 427 CINDEX_LINKAGE 428 CXString 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 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 */ 439 CINDEX_LINKAGE 440 unsigned 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 * \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 */ 455 CINDEX_LINKAGE 456 unsigned 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 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 */ 476 CINDEX_LINKAGE 477 unsigned 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 */ 484 CINDEX_LINKAGE 485 CXString 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 */ 492 CINDEX_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 AST 498 * node. 499 * 500 * \returns string containing an HTML tag. 501 */ 502 CINDEX_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 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 */ 535 CINDEX_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 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 */ 547 CINDEX_LINKAGE CXString clang_FullComment_getAsXML(CXComment Comment); 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 */ 554 typedef 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 */ 566 CINDEX_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 */ 574 CINDEX_LINKAGE void clang_disposeAPISet(CXAPISet api); 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 */ 592 CINDEX_LINKAGE CXString clang_getSymbolGraphForUSR(const char *usr, 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 */ 610 CINDEX_LINKAGE CXString clang_getSymbolGraphForCursor(CXCursor cursor); 611 612 /** 613 * @} 614 */ 615 616 LLVM_CLANG_C_EXTERN_C_END 617 618 #endif /* CLANG_C_DOCUMENTATION_H */ 619 620