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/ExternC.h" 19 #include "clang-c/Index.h" 20 21 LLVM_CLANG_C_EXTERN_C_BEGIN 22 23 /** 24 * \defgroup CINDEX_COMMENT Comment introspection 25 * 26 * The routines in this group provide access to information in documentation 27 * comments. These facilities are distinct from the core and may be subject to 28 * their own schedule of stability and deprecation. 29 * 30 * @{ 31 */ 32 33 /** 34 * A parsed comment. 35 */ 36 typedef struct { 37 const void *ASTNode; 38 CXTranslationUnit TranslationUnit; 39 } CXComment; 40 41 /** 42 * Given a cursor that represents a documentable entity (e.g., 43 * declaration), return the associated parsed comment as a 44 * \c CXComment_FullComment AST node. 45 */ 46 CINDEX_LINKAGE CXComment clang_Cursor_getParsedComment(CXCursor C); 47 48 /** 49 * Describes the type of the comment AST node (\c CXComment). A comment 50 * node can be considered block content (e. g., paragraph), inline content 51 * (plain text) or neither (the root AST node). 52 */ 53 enum CXCommentKind { 54 /** 55 * Null comment. No AST node is constructed at the requested location 56 * because there is no text or a syntax error. 57 */ 58 CXComment_Null = 0, 59 60 /** 61 * Plain text. Inline content. 62 */ 63 CXComment_Text = 1, 64 65 /** 66 * A command with word-like arguments that is considered inline content. 67 * 68 * For example: \\c command. 69 */ 70 CXComment_InlineCommand = 2, 71 72 /** 73 * HTML start tag with attributes (name-value pairs). Considered 74 * inline content. 75 * 76 * For example: 77 * \verbatim 78 * <br> <br /> <a href="http://example.org/"> 79 * \endverbatim 80 */ 81 CXComment_HTMLStartTag = 3, 82 83 /** 84 * HTML end tag. Considered inline content. 85 * 86 * For example: 87 * \verbatim 88 * </a> 89 * \endverbatim 90 */ 91 CXComment_HTMLEndTag = 4, 92 93 /** 94 * A paragraph, contains inline comment. The paragraph itself is 95 * block content. 96 */ 97 CXComment_Paragraph = 5, 98 99 /** 100 * A command that has zero or more word-like arguments (number of 101 * word-like arguments depends on command name) and a paragraph as an 102 * argument. Block command is block content. 103 * 104 * Paragraph argument is also a child of the block command. 105 * 106 * For example: \has 0 word-like arguments and a paragraph argument. 107 * 108 * AST nodes of special kinds that parser knows about (e. g., \\param 109 * command) have their own node kinds. 110 */ 111 CXComment_BlockCommand = 6, 112 113 /** 114 * A \\param or \\arg command that describes the function parameter 115 * (name, passing direction, description). 116 * 117 * For example: \\param [in] ParamName description. 118 */ 119 CXComment_ParamCommand = 7, 120 121 /** 122 * A \\tparam command that describes a template parameter (name and 123 * description). 124 * 125 * For example: \\tparam T description. 126 */ 127 CXComment_TParamCommand = 8, 128 129 /** 130 * A verbatim block command (e. g., preformatted code). Verbatim 131 * block has an opening and a closing command and contains multiple lines of 132 * text (\c CXComment_VerbatimBlockLine child nodes). 133 * 134 * For example: 135 * \\verbatim 136 * aaa 137 * \\endverbatim 138 */ 139 CXComment_VerbatimBlockCommand = 9, 140 141 /** 142 * A line of text that is contained within a 143 * CXComment_VerbatimBlockCommand node. 144 */ 145 CXComment_VerbatimBlockLine = 10, 146 147 /** 148 * A verbatim line command. Verbatim line has an opening command, 149 * a single line of text (up to the newline after the opening command) and 150 * has no closing command. 151 */ 152 CXComment_VerbatimLine = 11, 153 154 /** 155 * A full comment attached to a declaration, contains block content. 156 */ 157 CXComment_FullComment = 12 158 }; 159 160 /** 161 * The most appropriate rendering mode for an inline command, chosen on 162 * command semantics in Doxygen. 163 */ 164 enum CXCommentInlineCommandRenderKind { 165 /** 166 * Command argument should be rendered in a normal font. 167 */ 168 CXCommentInlineCommandRenderKind_Normal, 169 170 /** 171 * Command argument should be rendered in a bold font. 172 */ 173 CXCommentInlineCommandRenderKind_Bold, 174 175 /** 176 * Command argument should be rendered in a monospaced font. 177 */ 178 CXCommentInlineCommandRenderKind_Monospaced, 179 180 /** 181 * Command argument should be rendered emphasized (typically italic 182 * font). 183 */ 184 CXCommentInlineCommandRenderKind_Emphasized, 185 186 /** 187 * Command argument should not be rendered (since it only defines an anchor). 188 */ 189 CXCommentInlineCommandRenderKind_Anchor 190 }; 191 192 /** 193 * Describes parameter passing direction for \\param or \\arg command. 194 */ 195 enum CXCommentParamPassDirection { 196 /** 197 * The parameter is an input parameter. 198 */ 199 CXCommentParamPassDirection_In, 200 201 /** 202 * The parameter is an output parameter. 203 */ 204 CXCommentParamPassDirection_Out, 205 206 /** 207 * The parameter is an input and output parameter. 208 */ 209 CXCommentParamPassDirection_InOut 210 }; 211 212 /** 213 * \param Comment AST node of any kind. 214 * 215 * \returns the type of the AST node. 216 */ 217 CINDEX_LINKAGE enum CXCommentKind clang_Comment_getKind(CXComment Comment); 218 219 /** 220 * \param Comment AST node of any kind. 221 * 222 * \returns number of children of the AST node. 223 */ 224 CINDEX_LINKAGE unsigned clang_Comment_getNumChildren(CXComment Comment); 225 226 /** 227 * \param Comment AST node of any kind. 228 * 229 * \param ChildIdx child index (zero-based). 230 * 231 * \returns the specified child of the AST node. 232 */ 233 CINDEX_LINKAGE 234 CXComment clang_Comment_getChild(CXComment Comment, unsigned ChildIdx); 235 236 /** 237 * A \c CXComment_Paragraph node is considered whitespace if it contains 238 * only \c CXComment_Text nodes that are empty or whitespace. 239 * 240 * Other AST nodes (except \c CXComment_Paragraph and \c CXComment_Text) are 241 * never considered whitespace. 242 * 243 * \returns non-zero if \c Comment is whitespace. 244 */ 245 CINDEX_LINKAGE unsigned clang_Comment_isWhitespace(CXComment Comment); 246 247 /** 248 * \returns non-zero if \c Comment is inline content and has a newline 249 * immediately following it in the comment text. Newlines between paragraphs 250 * do not count. 251 */ 252 CINDEX_LINKAGE 253 unsigned clang_InlineContentComment_hasTrailingNewline(CXComment Comment); 254 255 /** 256 * \param Comment a \c CXComment_Text AST node. 257 * 258 * \returns text contained in the AST node. 259 */ 260 CINDEX_LINKAGE CXString clang_TextComment_getText(CXComment Comment); 261 262 /** 263 * \param Comment a \c CXComment_InlineCommand AST node. 264 * 265 * \returns name of the inline command. 266 */ 267 CINDEX_LINKAGE 268 CXString clang_InlineCommandComment_getCommandName(CXComment Comment); 269 270 /** 271 * \param Comment a \c CXComment_InlineCommand AST node. 272 * 273 * \returns the most appropriate rendering mode, chosen on command 274 * semantics in Doxygen. 275 */ 276 CINDEX_LINKAGE enum CXCommentInlineCommandRenderKind 277 clang_InlineCommandComment_getRenderKind(CXComment Comment); 278 279 /** 280 * \param Comment a \c CXComment_InlineCommand AST node. 281 * 282 * \returns number of command arguments. 283 */ 284 CINDEX_LINKAGE 285 unsigned clang_InlineCommandComment_getNumArgs(CXComment Comment); 286 287 /** 288 * \param Comment a \c CXComment_InlineCommand AST node. 289 * 290 * \param ArgIdx argument index (zero-based). 291 * 292 * \returns text of the specified argument. 293 */ 294 CINDEX_LINKAGE 295 CXString clang_InlineCommandComment_getArgText(CXComment Comment, 296 unsigned ArgIdx); 297 298 /** 299 * \param Comment a \c CXComment_HTMLStartTag or \c CXComment_HTMLEndTag AST 300 * node. 301 * 302 * \returns HTML tag name. 303 */ 304 CINDEX_LINKAGE CXString clang_HTMLTagComment_getTagName(CXComment Comment); 305 306 /** 307 * \param Comment a \c CXComment_HTMLStartTag AST node. 308 * 309 * \returns non-zero if tag is self-closing (for example, <br />). 310 */ 311 CINDEX_LINKAGE 312 unsigned clang_HTMLStartTagComment_isSelfClosing(CXComment Comment); 313 314 /** 315 * \param Comment a \c CXComment_HTMLStartTag AST node. 316 * 317 * \returns number of attributes (name-value pairs) attached to the start tag. 318 */ 319 CINDEX_LINKAGE unsigned clang_HTMLStartTag_getNumAttrs(CXComment Comment); 320 321 /** 322 * \param Comment a \c CXComment_HTMLStartTag AST node. 323 * 324 * \param AttrIdx attribute index (zero-based). 325 * 326 * \returns name of the specified attribute. 327 */ 328 CINDEX_LINKAGE 329 CXString clang_HTMLStartTag_getAttrName(CXComment Comment, unsigned AttrIdx); 330 331 /** 332 * \param Comment a \c CXComment_HTMLStartTag AST node. 333 * 334 * \param AttrIdx attribute index (zero-based). 335 * 336 * \returns value of the specified attribute. 337 */ 338 CINDEX_LINKAGE 339 CXString clang_HTMLStartTag_getAttrValue(CXComment Comment, unsigned AttrIdx); 340 341 /** 342 * \param Comment a \c CXComment_BlockCommand AST node. 343 * 344 * \returns name of the block command. 345 */ 346 CINDEX_LINKAGE 347 CXString clang_BlockCommandComment_getCommandName(CXComment Comment); 348 349 /** 350 * \param Comment a \c CXComment_BlockCommand AST node. 351 * 352 * \returns number of word-like arguments. 353 */ 354 CINDEX_LINKAGE 355 unsigned clang_BlockCommandComment_getNumArgs(CXComment Comment); 356 357 /** 358 * \param Comment a \c CXComment_BlockCommand AST node. 359 * 360 * \param ArgIdx argument index (zero-based). 361 * 362 * \returns text of the specified word-like argument. 363 */ 364 CINDEX_LINKAGE 365 CXString clang_BlockCommandComment_getArgText(CXComment Comment, 366 unsigned ArgIdx); 367 368 /** 369 * \param Comment a \c CXComment_BlockCommand or 370 * \c CXComment_VerbatimBlockCommand AST node. 371 * 372 * \returns paragraph argument of the block command. 373 */ 374 CINDEX_LINKAGE 375 CXComment clang_BlockCommandComment_getParagraph(CXComment Comment); 376 377 /** 378 * \param Comment a \c CXComment_ParamCommand AST node. 379 * 380 * \returns parameter name. 381 */ 382 CINDEX_LINKAGE 383 CXString clang_ParamCommandComment_getParamName(CXComment Comment); 384 385 /** 386 * \param Comment a \c CXComment_ParamCommand AST node. 387 * 388 * \returns non-zero if the parameter that this AST node represents was found 389 * in the function prototype and \c clang_ParamCommandComment_getParamIndex 390 * function will return a meaningful value. 391 */ 392 CINDEX_LINKAGE 393 unsigned clang_ParamCommandComment_isParamIndexValid(CXComment Comment); 394 395 /** 396 * \param Comment a \c CXComment_ParamCommand AST node. 397 * 398 * \returns zero-based parameter index in function prototype. 399 */ 400 CINDEX_LINKAGE 401 unsigned clang_ParamCommandComment_getParamIndex(CXComment Comment); 402 403 /** 404 * \param Comment a \c CXComment_ParamCommand AST node. 405 * 406 * \returns non-zero if parameter passing direction was specified explicitly in 407 * the comment. 408 */ 409 CINDEX_LINKAGE 410 unsigned clang_ParamCommandComment_isDirectionExplicit(CXComment Comment); 411 412 /** 413 * \param Comment a \c CXComment_ParamCommand AST node. 414 * 415 * \returns parameter passing direction. 416 */ 417 CINDEX_LINKAGE 418 enum CXCommentParamPassDirection clang_ParamCommandComment_getDirection( 419 CXComment Comment); 420 421 /** 422 * \param Comment a \c CXComment_TParamCommand AST node. 423 * 424 * \returns template parameter name. 425 */ 426 CINDEX_LINKAGE 427 CXString clang_TParamCommandComment_getParamName(CXComment Comment); 428 429 /** 430 * \param Comment a \c CXComment_TParamCommand AST node. 431 * 432 * \returns non-zero if the parameter that this AST node represents was found 433 * in the template parameter list and 434 * \c clang_TParamCommandComment_getDepth and 435 * \c clang_TParamCommandComment_getIndex functions will return a meaningful 436 * value. 437 */ 438 CINDEX_LINKAGE 439 unsigned clang_TParamCommandComment_isParamPositionValid(CXComment Comment); 440 441 /** 442 * \param Comment a \c CXComment_TParamCommand AST node. 443 * 444 * \returns zero-based nesting depth of this parameter in the template parameter list. 445 * 446 * For example, 447 * \verbatim 448 * template<typename C, template<typename T> class TT> 449 * void test(TT<int> aaa); 450 * \endverbatim 451 * for C and TT nesting depth is 0, 452 * for T nesting depth is 1. 453 */ 454 CINDEX_LINKAGE 455 unsigned clang_TParamCommandComment_getDepth(CXComment Comment); 456 457 /** 458 * \param Comment a \c CXComment_TParamCommand AST node. 459 * 460 * \returns zero-based parameter index in the template parameter list at a 461 * given nesting depth. 462 * 463 * For example, 464 * \verbatim 465 * template<typename C, template<typename T> class TT> 466 * void test(TT<int> aaa); 467 * \endverbatim 468 * for C and TT nesting depth is 0, so we can ask for index at depth 0: 469 * at depth 0 C's index is 0, TT's index is 1. 470 * 471 * For T nesting depth is 1, so we can ask for index at depth 0 and 1: 472 * at depth 0 T's index is 1 (same as TT's), 473 * at depth 1 T's index is 0. 474 */ 475 CINDEX_LINKAGE 476 unsigned clang_TParamCommandComment_getIndex(CXComment Comment, unsigned Depth); 477 478 /** 479 * \param Comment a \c CXComment_VerbatimBlockLine AST node. 480 * 481 * \returns text contained in the AST node. 482 */ 483 CINDEX_LINKAGE 484 CXString clang_VerbatimBlockLineComment_getText(CXComment Comment); 485 486 /** 487 * \param Comment a \c CXComment_VerbatimLine AST node. 488 * 489 * \returns text contained in the AST node. 490 */ 491 CINDEX_LINKAGE CXString clang_VerbatimLineComment_getText(CXComment Comment); 492 493 /** 494 * Convert an HTML tag AST node to string. 495 * 496 * \param Comment a \c CXComment_HTMLStartTag or \c CXComment_HTMLEndTag AST 497 * node. 498 * 499 * \returns string containing an HTML tag. 500 */ 501 CINDEX_LINKAGE CXString clang_HTMLTagComment_getAsString(CXComment Comment); 502 503 /** 504 * Convert a given full parsed comment to an HTML fragment. 505 * 506 * Specific details of HTML layout are subject to change. Don't try to parse 507 * this HTML back into an AST, use other APIs instead. 508 * 509 * Currently the following CSS classes are used: 510 * \li "para-brief" for \paragraph and equivalent commands; 511 * \li "para-returns" for \\returns paragraph and equivalent commands; 512 * \li "word-returns" for the "Returns" word in \\returns paragraph. 513 * 514 * Function argument documentation is rendered as a \<dl\> list with arguments 515 * sorted in function prototype order. CSS classes used: 516 * \li "param-name-index-NUMBER" for parameter name (\<dt\>); 517 * \li "param-descr-index-NUMBER" for parameter description (\<dd\>); 518 * \li "param-name-index-invalid" and "param-descr-index-invalid" are used if 519 * parameter index is invalid. 520 * 521 * Template parameter documentation is rendered as a \<dl\> list with 522 * parameters sorted in template parameter list order. CSS classes used: 523 * \li "tparam-name-index-NUMBER" for parameter name (\<dt\>); 524 * \li "tparam-descr-index-NUMBER" for parameter description (\<dd\>); 525 * \li "tparam-name-index-other" and "tparam-descr-index-other" are used for 526 * names inside template template parameters; 527 * \li "tparam-name-index-invalid" and "tparam-descr-index-invalid" are used if 528 * parameter position is invalid. 529 * 530 * \param Comment a \c CXComment_FullComment AST node. 531 * 532 * \returns string containing an HTML fragment. 533 */ 534 CINDEX_LINKAGE CXString clang_FullComment_getAsHTML(CXComment Comment); 535 536 /** 537 * Convert a given full parsed comment to an XML document. 538 * 539 * A Relax NG schema for the XML can be found in comment-xml-schema.rng file 540 * inside clang source tree. 541 * 542 * \param Comment a \c CXComment_FullComment AST node. 543 * 544 * \returns string containing an XML document. 545 */ 546 CINDEX_LINKAGE CXString clang_FullComment_getAsXML(CXComment Comment); 547 548 /** 549 * @} 550 */ 551 552 LLVM_CLANG_C_EXTERN_C_END 553 554 #endif /* CLANG_C_DOCUMENTATION_H */ 555 556