extra/clang-c/Documentation.h

   1 /*==-- clang-c/Documentation.h - Utilities for comment processing -*- C -*-===*\
   2 |*                                                                            *|
   3 |*                     The LLVM Compiler Infrastructure                       *|
   4 |*                                                                            *|
   5 |* This file is distributed under the University of Illinois Open Source      *|
   6 |* License. See LICENSE.TXT for details.                                      *|
   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/Index.h"
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 #endif
  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  * \brief A parsed comment.
  36  */
  37 typedef struct {
  38   const void *ASTNode;
  39   CXTranslationUnit TranslationUnit;
  40 } CXComment;
  41
  42 /**
  43  * \brief 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  * \brief 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    * \brief 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    * \brief Plain text.  Inline content.
  63    */
  64   CXComment_Text = 1,
  65
  66   /**
  67    * \brief 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    * \brief 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    * \brief HTML end tag.  Considered inline content.
  86    *
  87    * For example:
  88    * \verbatim
  89    * </a>
  90    * \endverbatim
  91    */
  92   CXComment_HTMLEndTag = 4,
  93
  94   /**
  95    * \brief A paragraph, contains inline comment.  The paragraph itself is
  96    * block content.
  97    */
  98   CXComment_Paragraph = 5,
  99
 100   /**
 101    * \brief 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: \\brief 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    * \brief 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    * \brief 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    * \brief 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    * \brief A line of text that is contained within a
 144    * CXComment_VerbatimBlockCommand node.
 145    */
 146   CXComment_VerbatimBlockLine = 10,
 147
 148   /**
 149    * \brief 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    * \brief A full comment attached to a declaration, contains block content.
 157    */
 158   CXComment_FullComment = 12
 159 };
 160
 161 /**
 162  * \brief The most appropriate rendering mode for an inline command, chosen on
 163  * command semantics in Doxygen.
 164  */
 165 enum CXCommentInlineCommandRenderKind {
 166   /**
 167    * \brief Command argument should be rendered in a normal font.
 168    */
 169   CXCommentInlineCommandRenderKind_Normal,
 170
 171   /**
 172    * \brief Command argument should be rendered in a bold font.
 173    */
 174   CXCommentInlineCommandRenderKind_Bold,
 175
 176   /**
 177    * \brief Command argument should be rendered in a monospaced font.
 178    */
 179   CXCommentInlineCommandRenderKind_Monospaced,
 180
 181   /**
 182    * \brief Command argument should be rendered emphasized (typically italic
 183    * font).
 184    */
 185   CXCommentInlineCommandRenderKind_Emphasized
 186 };
 187
 188 /**
 189  * \brief Describes parameter passing direction for \\param or \\arg command.
 190  */
 191 enum CXCommentParamPassDirection {
 192   /**
 193    * \brief The parameter is an input parameter.
 194    */
 195   CXCommentParamPassDirection_In,
 196
 197   /**
 198    * \brief The parameter is an output parameter.
 199    */
 200   CXCommentParamPassDirection_Out,
 201
 202   /**
 203    * \brief The parameter is an input and output parameter.
 204    */
 205   CXCommentParamPassDirection_InOut
 206 };
 207
 208 /**
 209  * \param Comment AST node of any kind.
 210  *
 211  * \returns the type of the AST node.
 212  */
 213 CINDEX_LINKAGE enum CXCommentKind clang_Comment_getKind(CXComment Comment);
 214
 215 /**
 216  * \param Comment AST node of any kind.
 217  *
 218  * \returns number of children of the AST node.
 219  */
 220 CINDEX_LINKAGE unsigned clang_Comment_getNumChildren(CXComment Comment);
 221
 222 /**
 223  * \param Comment AST node of any kind.
 224  *
 225  * \param ChildIdx child index (zero-based).
 226  *
 227  * \returns the specified child of the AST node.
 228  */
 229 CINDEX_LINKAGE
 230 CXComment clang_Comment_getChild(CXComment Comment, unsigned ChildIdx);
 231
 232 /**
 233  * \brief A \c CXComment_Paragraph node is considered whitespace if it contains
 234  * only \c CXComment_Text nodes that are empty or whitespace.
 235  *
 236  * Other AST nodes (except \c CXComment_Paragraph and \c CXComment_Text) are
 237  * never considered whitespace.
 238  *
 239  * \returns non-zero if \c Comment is whitespace.
 240  */
 241 CINDEX_LINKAGE unsigned clang_Comment_isWhitespace(CXComment Comment);
 242
 243 /**
 244  * \returns non-zero if \c Comment is inline content and has a newline
 245  * immediately following it in the comment text.  Newlines between paragraphs
 246  * do not count.
 247  */
 248 CINDEX_LINKAGE
 249 unsigned clang_InlineContentComment_hasTrailingNewline(CXComment Comment);
 250
 251 /**
 252  * \param Comment a \c CXComment_Text AST node.
 253  *
 254  * \returns text contained in the AST node.
 255  */
 256 CINDEX_LINKAGE CXString clang_TextComment_getText(CXComment Comment);
 257
 258 /**
 259  * \param Comment a \c CXComment_InlineCommand AST node.
 260  *
 261  * \returns name of the inline command.
 262  */
 263 CINDEX_LINKAGE
 264 CXString clang_InlineCommandComment_getCommandName(CXComment Comment);
 265
 266 /**
 267  * \param Comment a \c CXComment_InlineCommand AST node.
 268  *
 269  * \returns the most appropriate rendering mode, chosen on command
 270  * semantics in Doxygen.
 271  */
 272 CINDEX_LINKAGE enum CXCommentInlineCommandRenderKind
 273 clang_InlineCommandComment_getRenderKind(CXComment Comment);
 274
 275 /**
 276  * \param Comment a \c CXComment_InlineCommand AST node.
 277  *
 278  * \returns number of command arguments.
 279  */
 280 CINDEX_LINKAGE
 281 unsigned clang_InlineCommandComment_getNumArgs(CXComment Comment);
 282
 283 /**
 284  * \param Comment a \c CXComment_InlineCommand AST node.
 285  *
 286  * \param ArgIdx argument index (zero-based).
 287  *
 288  * \returns text of the specified argument.
 289  */
 290 CINDEX_LINKAGE
 291 CXString clang_InlineCommandComment_getArgText(CXComment Comment,
 292                                                unsigned ArgIdx);
 293
 294 /**
 295  * \param Comment a \c CXComment_HTMLStartTag or \c CXComment_HTMLEndTag AST
 296  * node.
 297  *
 298  * \returns HTML tag name.
 299  */
 300 CINDEX_LINKAGE CXString clang_HTMLTagComment_getTagName(CXComment Comment);
 301
 302 /**
 303  * \param Comment a \c CXComment_HTMLStartTag AST node.
 304  *
 305  * \returns non-zero if tag is self-closing (for example, &lt;br /&gt;).
 306  */
 307 CINDEX_LINKAGE
 308 unsigned 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 CINDEX_LINKAGE unsigned 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 CINDEX_LINKAGE
 325 CXString clang_HTMLStartTag_getAttrName(CXComment Comment, unsigned AttrIdx);
 326
 327 /**
 328  * \param Comment a \c CXComment_HTMLStartTag AST node.
 329  *
 330  * \param AttrIdx attribute index (zero-based).
 331  *
 332  * \returns value of the specified attribute.
 333  */
 334 CINDEX_LINKAGE
 335 CXString clang_HTMLStartTag_getAttrValue(CXComment Comment, unsigned AttrIdx);
 336
 337 /**
 338  * \param Comment a \c CXComment_BlockCommand AST node.
 339  *
 340  * \returns name of the block command.
 341  */
 342 CINDEX_LINKAGE
 343 CXString clang_BlockCommandComment_getCommandName(CXComment Comment);
 344
 345 /**
 346  * \param Comment a \c CXComment_BlockCommand AST node.
 347  *
 348  * \returns number of word-like arguments.
 349  */
 350 CINDEX_LINKAGE
 351 unsigned clang_BlockCommandComment_getNumArgs(CXComment Comment);
 352
 353 /**
 354  * \param Comment a \c CXComment_BlockCommand AST node.
 355  *
 356  * \param ArgIdx argument index (zero-based).
 357  *
 358  * \returns text of the specified word-like argument.
 359  */
 360 CINDEX_LINKAGE
 361 CXString clang_BlockCommandComment_getArgText(CXComment Comment,
 362                                               unsigned ArgIdx);
 363
 364 /**
 365  * \param Comment a \c CXComment_BlockCommand or
 366  * \c CXComment_VerbatimBlockCommand AST node.
 367  *
 368  * \returns paragraph argument of the block command.
 369  */
 370 CINDEX_LINKAGE
 371 CXComment clang_BlockCommandComment_getParagraph(CXComment Comment);
 372
 373 /**
 374  * \param Comment a \c CXComment_ParamCommand AST node.
 375  *
 376  * \returns parameter name.
 377  */
 378 CINDEX_LINKAGE
 379 CXString clang_ParamCommandComment_getParamName(CXComment Comment);
 380
 381 /**
 382  * \param Comment a \c CXComment_ParamCommand AST node.
 383  *
 384  * \returns non-zero if the parameter that this AST node represents was found
 385  * in the function prototype and \c clang_ParamCommandComment_getParamIndex
 386  * function will return a meaningful value.
 387  */
 388 CINDEX_LINKAGE
 389 unsigned clang_ParamCommandComment_isParamIndexValid(CXComment Comment);
 390
 391 /**
 392  * \param Comment a \c CXComment_ParamCommand AST node.
 393  *
 394  * \returns zero-based parameter index in function prototype.
 395  */
 396 CINDEX_LINKAGE
 397 unsigned clang_ParamCommandComment_getParamIndex(CXComment Comment);
 398
 399 /**
 400  * \param Comment a \c CXComment_ParamCommand AST node.
 401  *
 402  * \returns non-zero if parameter passing direction was specified explicitly in
 403  * the comment.
 404  */
 405 CINDEX_LINKAGE
 406 unsigned clang_ParamCommandComment_isDirectionExplicit(CXComment Comment);
 407
 408 /**
 409  * \param Comment a \c CXComment_ParamCommand AST node.
 410  *
 411  * \returns parameter passing direction.
 412  */
 413 CINDEX_LINKAGE
 414 enum CXCommentParamPassDirection clang_ParamCommandComment_getDirection(
 415                                                             CXComment Comment);
 416
 417 /**
 418  * \param Comment a \c CXComment_TParamCommand AST node.
 419  *
 420  * \returns template parameter name.
 421  */
 422 CINDEX_LINKAGE
 423 CXString clang_TParamCommandComment_getParamName(CXComment Comment);
 424
 425 /**
 426  * \param Comment a \c CXComment_TParamCommand AST node.
 427  *
 428  * \returns non-zero if the parameter that this AST node represents was found
 429  * in the template parameter list and
 430  * \c clang_TParamCommandComment_getDepth and
 431  * \c clang_TParamCommandComment_getIndex functions will return a meaningful
 432  * value.
 433  */
 434 CINDEX_LINKAGE
 435 unsigned clang_TParamCommandComment_isParamPositionValid(CXComment Comment);
 436
 437 /**
 438  * \param Comment a \c CXComment_TParamCommand AST node.
 439  *
 440  * \returns zero-based nesting depth of this parameter in the template parameter list.
 441  *
 442  * For example,
 443  * \verbatim
 444  *     template<typename C, template<typename T> class TT>
 445  *     void test(TT<int> aaa);
 446  * \endverbatim
 447  * for C and TT nesting depth is 0,
 448  * for T nesting depth is 1.
 449  */
 450 CINDEX_LINKAGE
 451 unsigned clang_TParamCommandComment_getDepth(CXComment Comment);
 452
 453 /**
 454  * \param Comment a \c CXComment_TParamCommand AST node.
 455  *
 456  * \returns zero-based parameter index in the template parameter list at a
 457  * given nesting depth.
 458  *
 459  * For example,
 460  * \verbatim
 461  *     template<typename C, template<typename T> class TT>
 462  *     void test(TT<int> aaa);
 463  * \endverbatim
 464  * for C and TT nesting depth is 0, so we can ask for index at depth 0:
 465  * at depth 0 C's index is 0, TT's index is 1.
 466  *
 467  * For T nesting depth is 1, so we can ask for index at depth 0 and 1:
 468  * at depth 0 T's index is 1 (same as TT's),
 469  * at depth 1 T's index is 0.
 470  */
 471 CINDEX_LINKAGE
 472 unsigned clang_TParamCommandComment_getIndex(CXComment Comment, unsigned Depth);
 473
 474 /**
 475  * \param Comment a \c CXComment_VerbatimBlockLine AST node.
 476  *
 477  * \returns text contained in the AST node.
 478  */
 479 CINDEX_LINKAGE
 480 CXString clang_VerbatimBlockLineComment_getText(CXComment Comment);
 481
 482 /**
 483  * \param Comment a \c CXComment_VerbatimLine AST node.
 484  *
 485  * \returns text contained in the AST node.
 486  */
 487 CINDEX_LINKAGE CXString clang_VerbatimLineComment_getText(CXComment Comment);
 488
 489 /**
 490  * \brief Convert an HTML tag AST node to string.
 491  *
 492  * \param Comment a \c CXComment_HTMLStartTag or \c CXComment_HTMLEndTag AST
 493  * node.
 494  *
 495  * \returns string containing an HTML tag.
 496  */
 497 CINDEX_LINKAGE CXString clang_HTMLTagComment_getAsString(CXComment Comment);
 498
 499 /**
 500  * \brief Convert a given full parsed comment to an HTML fragment.
 501  *
 502  * Specific details of HTML layout are subject to change.  Don't try to parse
 503  * this HTML back into an AST, use other APIs instead.
 504  *
 505  * Currently the following CSS classes are used:
 506  * \li "para-brief" for \\brief paragraph and equivalent commands;
 507  * \li "para-returns" for \\returns paragraph and equivalent commands;
 508  * \li "word-returns" for the "Returns" word in \\returns paragraph.
 509  *
 510  * Function argument documentation is rendered as a \<dl\> list with arguments
 511  * sorted in function prototype order.  CSS classes used:
 512  * \li "param-name-index-NUMBER" for parameter name (\<dt\>);
 513  * \li "param-descr-index-NUMBER" for parameter description (\<dd\>);
 514  * \li "param-name-index-invalid" and "param-descr-index-invalid" are used if
 515  * parameter index is invalid.
 516  *
 517  * Template parameter documentation is rendered as a \<dl\> list with
 518  * parameters sorted in template parameter list order.  CSS classes used:
 519  * \li "tparam-name-index-NUMBER" for parameter name (\<dt\>);
 520  * \li "tparam-descr-index-NUMBER" for parameter description (\<dd\>);
 521  * \li "tparam-name-index-other" and "tparam-descr-index-other" are used for
 522  * names inside template template parameters;
 523  * \li "tparam-name-index-invalid" and "tparam-descr-index-invalid" are used if
 524  * parameter position is invalid.
 525  *
 526  * \param Comment a \c CXComment_FullComment AST node.
 527  *
 528  * \returns string containing an HTML fragment.
 529  */
 530 CINDEX_LINKAGE CXString clang_FullComment_getAsHTML(CXComment Comment);
 531
 532 /**
 533  * \brief Convert a given full parsed comment to an XML document.
 534  *
 535  * A Relax NG schema for the XML can be found in comment-xml-schema.rng file
 536  * inside clang source tree.
 537  *
 538  * \param Comment a \c CXComment_FullComment AST node.
 539  *
 540  * \returns string containing an XML document.
 541  */
 542 CINDEX_LINKAGE CXString clang_FullComment_getAsXML(CXComment Comment);
 543
 544 /**
 545  * @}
 546  */
 547
 548
 549 #ifdef __cplusplus
 550 }
 551 #endif
 552
 553 #endif /* CLANG_C_DOCUMENTATION_H */
 554