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