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 module clang.c.Documentation; 16 17 public import clang.c.CXString; 18 public import clang.c.Index; 19 20 extern (C): 21 22 /** 23 * \defgroup CINDEX_COMMENT Comment introspection 24 * 25 * The routines in this group provide access to information in documentation 26 * comments. These facilities are distinct from the core and may be subject to 27 * their own schedule of stability and deprecation. 28 * 29 * @{ 30 */ 31 32 /** 33 * A parsed comment. 34 */ 35 struct CXComment 36 { 37 const(void)* ASTNode; 38 CXTranslationUnit TranslationUnit; 39 } 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 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 /** 56 * Null comment. No AST node is constructed at the requested location 57 * because there is no text or a syntax error. 58 */ 59 null_ = 0, 60 61 /** 62 * Plain text. Inline content. 63 */ 64 text = 1, 65 66 /** 67 * A command with word-like arguments that is considered inline content. 68 * 69 * For example: \\c command. 70 */ 71 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 htmlStartTag = 3, 83 84 /** 85 * HTML end tag. Considered inline content. 86 * 87 * For example: 88 * \verbatim 89 * </a> 90 * \endverbatim 91 */ 92 htmlEndTag = 4, 93 94 /** 95 * A paragraph, contains inline comment. The paragraph itself is 96 * block content. 97 */ 98 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 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 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 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 verbatimBlockCommand = 9, 141 142 /** 143 * A line of text that is contained within a 144 * CXComment_VerbatimBlockCommand node. 145 */ 146 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 verbatimLine = 11, 154 155 /** 156 * A full comment attached to a declaration, contains block content. 157 */ 158 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 /** 168 * Command argument should be rendered in a normal font. 169 */ 170 normal = 0, 171 172 /** 173 * Command argument should be rendered in a bold font. 174 */ 175 bold = 1, 176 177 /** 178 * Command argument should be rendered in a monospaced font. 179 */ 180 monospaced = 2, 181 182 /** 183 * Command argument should be rendered emphasized (typically italic 184 * font). 185 */ 186 emphasized = 3, 187 188 /** 189 * Command argument should not be rendered (since it only defines an anchor). 190 */ 191 anchor = 4 192 } 193 194 /** 195 * Describes parameter passing direction for \\param or \\arg command. 196 */ 197 enum CXCommentParamPassDirection 198 { 199 /** 200 * The parameter is an input parameter. 201 */ 202 in_ = 0, 203 204 /** 205 * The parameter is an output parameter. 206 */ 207 out_ = 1, 208 209 /** 210 * The parameter is an input and output parameter. 211 */ 212 inOut = 2 213 } 214 215 /** 216 * \param Comment AST node of any kind. 217 * 218 * \returns the type of the AST node. 219 */ 220 CXCommentKind clang_Comment_getKind(CXComment Comment); 221 222 /** 223 * \param Comment AST node of any kind. 224 * 225 * \returns number of children of the AST node. 226 */ 227 uint clang_Comment_getNumChildren(CXComment Comment); 228 229 /** 230 * \param Comment AST node of any kind. 231 * 232 * \param ChildIdx child index (zero-based). 233 * 234 * \returns the specified child of the AST node. 235 */ 236 CXComment clang_Comment_getChild(CXComment Comment, uint ChildIdx); 237 238 /** 239 * A \c CXComment_Paragraph node is considered whitespace if it contains 240 * only \c CXComment_Text nodes that are empty or whitespace. 241 * 242 * Other AST nodes (except \c CXComment_Paragraph and \c CXComment_Text) are 243 * never considered whitespace. 244 * 245 * \returns non-zero if \c Comment is whitespace. 246 */ 247 uint clang_Comment_isWhitespace(CXComment Comment); 248 249 /** 250 * \returns non-zero if \c Comment is inline content and has a newline 251 * immediately following it in the comment text. Newlines between paragraphs 252 * do not count. 253 */ 254 uint 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 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 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 CXCommentInlineCommandRenderKind clang_InlineCommandComment_getRenderKind( 277 CXComment Comment); 278 279 /** 280 * \param Comment a \c CXComment_InlineCommand AST node. 281 * 282 * \returns number of command arguments. 283 */ 284 uint clang_InlineCommandComment_getNumArgs(CXComment Comment); 285 286 /** 287 * \param Comment a \c CXComment_InlineCommand AST node. 288 * 289 * \param ArgIdx argument index (zero-based). 290 * 291 * \returns text of the specified argument. 292 */ 293 CXString clang_InlineCommandComment_getArgText(CXComment Comment, uint ArgIdx); 294 295 /** 296 * \param Comment a \c CXComment_HTMLStartTag or \c CXComment_HTMLEndTag AST 297 * node. 298 * 299 * \returns HTML tag name. 300 */ 301 CXString clang_HTMLTagComment_getTagName(CXComment Comment); 302 303 /** 304 * \param Comment a \c CXComment_HTMLStartTag AST node. 305 * 306 * \returns non-zero if tag is self-closing (for example, <br />). 307 */ 308 uint 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 */ 315 uint 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 */ 324 CXString clang_HTMLStartTag_getAttrName(CXComment Comment, uint AttrIdx); 325 326 /** 327 * \param Comment a \c CXComment_HTMLStartTag AST node. 328 * 329 * \param AttrIdx attribute index (zero-based). 330 * 331 * \returns value of the specified attribute. 332 */ 333 CXString clang_HTMLStartTag_getAttrValue(CXComment Comment, uint AttrIdx); 334 335 /** 336 * \param Comment a \c CXComment_BlockCommand AST node. 337 * 338 * \returns name of the block command. 339 */ 340 CXString clang_BlockCommandComment_getCommandName(CXComment Comment); 341 342 /** 343 * \param Comment a \c CXComment_BlockCommand AST node. 344 * 345 * \returns number of word-like arguments. 346 */ 347 uint clang_BlockCommandComment_getNumArgs(CXComment Comment); 348 349 /** 350 * \param Comment a \c CXComment_BlockCommand AST node. 351 * 352 * \param ArgIdx argument index (zero-based). 353 * 354 * \returns text of the specified word-like argument. 355 */ 356 CXString clang_BlockCommandComment_getArgText(CXComment Comment, uint ArgIdx); 357 358 /** 359 * \param Comment a \c CXComment_BlockCommand or 360 * \c CXComment_VerbatimBlockCommand AST node. 361 * 362 * \returns paragraph argument of the block command. 363 */ 364 CXComment clang_BlockCommandComment_getParagraph(CXComment Comment); 365 366 /** 367 * \param Comment a \c CXComment_ParamCommand AST node. 368 * 369 * \returns parameter name. 370 */ 371 CXString clang_ParamCommandComment_getParamName(CXComment Comment); 372 373 /** 374 * \param Comment a \c CXComment_ParamCommand AST node. 375 * 376 * \returns non-zero if the parameter that this AST node represents was found 377 * in the function prototype and \c clang_ParamCommandComment_getParamIndex 378 * function will return a meaningful value. 379 */ 380 uint clang_ParamCommandComment_isParamIndexValid(CXComment Comment); 381 382 /** 383 * \param Comment a \c CXComment_ParamCommand AST node. 384 * 385 * \returns zero-based parameter index in function prototype. 386 */ 387 uint clang_ParamCommandComment_getParamIndex(CXComment Comment); 388 389 /** 390 * \param Comment a \c CXComment_ParamCommand AST node. 391 * 392 * \returns non-zero if parameter passing direction was specified explicitly in 393 * the comment. 394 */ 395 uint clang_ParamCommandComment_isDirectionExplicit(CXComment Comment); 396 397 /** 398 * \param Comment a \c CXComment_ParamCommand AST node. 399 * 400 * \returns parameter passing direction. 401 */ 402 CXCommentParamPassDirection clang_ParamCommandComment_getDirection( 403 CXComment Comment); 404 405 /** 406 * \param Comment a \c CXComment_TParamCommand AST node. 407 * 408 * \returns template parameter name. 409 */ 410 CXString clang_TParamCommandComment_getParamName(CXComment Comment); 411 412 /** 413 * \param Comment a \c CXComment_TParamCommand AST node. 414 * 415 * \returns non-zero if the parameter that this AST node represents was found 416 * in the template parameter list and 417 * \c clang_TParamCommandComment_getDepth and 418 * \c clang_TParamCommandComment_getIndex functions will return a meaningful 419 * value. 420 */ 421 uint clang_TParamCommandComment_isParamPositionValid(CXComment Comment); 422 423 /** 424 * \param Comment a \c CXComment_TParamCommand AST node. 425 * 426 * \returns zero-based nesting depth of this parameter in the template parameter list. 427 * 428 * For example, 429 * \verbatim 430 * template<typename C, template<typename T> class TT> 431 * void test(TT<int> aaa); 432 * \endverbatim 433 * for C and TT nesting depth is 0, 434 * for T nesting depth is 1. 435 */ 436 uint clang_TParamCommandComment_getDepth(CXComment Comment); 437 438 /** 439 * \param Comment a \c CXComment_TParamCommand AST node. 440 * 441 * \returns zero-based parameter index in the template parameter list at a 442 * given nesting depth. 443 * 444 * For example, 445 * \verbatim 446 * template<typename C, template<typename T> class TT> 447 * void test(TT<int> aaa); 448 * \endverbatim 449 * for C and TT nesting depth is 0, so we can ask for index at depth 0: 450 * at depth 0 C's index is 0, TT's index is 1. 451 * 452 * For T nesting depth is 1, so we can ask for index at depth 0 and 1: 453 * at depth 0 T's index is 1 (same as TT's), 454 * at depth 1 T's index is 0. 455 */ 456 uint clang_TParamCommandComment_getIndex(CXComment Comment, uint Depth); 457 458 /** 459 * \param Comment a \c CXComment_VerbatimBlockLine AST node. 460 * 461 * \returns text contained in the AST node. 462 */ 463 CXString clang_VerbatimBlockLineComment_getText(CXComment Comment); 464 465 /** 466 * \param Comment a \c CXComment_VerbatimLine AST node. 467 * 468 * \returns text contained in the AST node. 469 */ 470 CXString clang_VerbatimLineComment_getText(CXComment Comment); 471 472 /** 473 * Convert an HTML tag AST node to string. 474 * 475 * \param Comment a \c CXComment_HTMLStartTag or \c CXComment_HTMLEndTag AST 476 * node. 477 * 478 * \returns string containing an HTML tag. 479 */ 480 CXString clang_HTMLTagComment_getAsString(CXComment Comment); 481 482 /** 483 * Convert a given full parsed comment to an HTML fragment. 484 * 485 * Specific details of HTML layout are subject to change. Don't try to parse 486 * this HTML back into an AST, use other APIs instead. 487 * 488 * Currently the following CSS classes are used: 489 * \li "para-brief" for \paragraph and equivalent commands; 490 * \li "para-returns" for \\returns paragraph and equivalent commands; 491 * \li "word-returns" for the "Returns" word in \\returns paragraph. 492 * 493 * Function argument documentation is rendered as a \<dl\> list with arguments 494 * sorted in function prototype order. CSS classes used: 495 * \li "param-name-index-NUMBER" for parameter name (\<dt\>); 496 * \li "param-descr-index-NUMBER" for parameter description (\<dd\>); 497 * \li "param-name-index-invalid" and "param-descr-index-invalid" are used if 498 * parameter index is invalid. 499 * 500 * Template parameter documentation is rendered as a \<dl\> list with 501 * parameters sorted in template parameter list order. CSS classes used: 502 * \li "tparam-name-index-NUMBER" for parameter name (\<dt\>); 503 * \li "tparam-descr-index-NUMBER" for parameter description (\<dd\>); 504 * \li "tparam-name-index-other" and "tparam-descr-index-other" are used for 505 * names inside template template parameters; 506 * \li "tparam-name-index-invalid" and "tparam-descr-index-invalid" are used if 507 * parameter position is invalid. 508 * 509 * \param Comment a \c CXComment_FullComment AST node. 510 * 511 * \returns string containing an HTML fragment. 512 */ 513 CXString clang_FullComment_getAsHTML(CXComment Comment); 514 515 /** 516 * Convert a given full parsed comment to an XML document. 517 * 518 * A Relax NG schema for the XML can be found in comment-xml-schema.rng file 519 * inside clang source tree. 520 * 521 * \param Comment a \c CXComment_FullComment AST node. 522 * 523 * \returns string containing an XML document. 524 */ 525 CXString clang_FullComment_getAsXML(CXComment Comment); 526 527 /** 528 * @} 529 */ 530 531 /* CLANG_C_DOCUMENTATION_H */