contrib/llvm-project/clang/include/clang-c/Documentation.h

   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, &lt;br /&gt;).
 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