include/clang-c/Documentation.h

0001 /*==-- clang-c/Documentation.h - Utilities for comment processing -*- C -*-===*\
0002 |*                                                                            *|
0003 |* Part of the LLVM Project, under the Apache License v2.0 with LLVM          *|
0004 |* Exceptions.                                                                *|
0005 |* See https://llvm.org/LICENSE.txt for license information.                  *|
0006 |* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception                    *|
0007 |*                                                                            *|
0008 |*===----------------------------------------------------------------------===*|
0009 |*                                                                            *|
0010 |* This header provides a supplementary interface for inspecting              *|
0011 |* documentation comments.                                                    *|
0012 |*                                                                            *|
0013 \*===----------------------------------------------------------------------===*/
0014
0015 #ifndef LLVM_CLANG_C_DOCUMENTATION_H
0016 #define LLVM_CLANG_C_DOCUMENTATION_H
0017
0018 #include "clang-c/CXErrorCode.h"
0019 #include "clang-c/ExternC.h"
0020 #include "clang-c/Index.h"
0021
0022 LLVM_CLANG_C_EXTERN_C_BEGIN
0023
0024 /**
0025  * \defgroup CINDEX_COMMENT Comment introspection
0026  *
0027  * The routines in this group provide access to information in documentation
0028  * comments. These facilities are distinct from the core and may be subject to
0029  * their own schedule of stability and deprecation.
0030  *
0031  * @{
0032  */
0033
0034 /**
0035  * A parsed comment.
0036  */
0037 typedef struct {
0038   const void *ASTNode;
0039   CXTranslationUnit TranslationUnit;
0040 } CXComment;
0041
0042 /**
0043  * Given a cursor that represents a documentable entity (e.g.,
0044  * declaration), return the associated parsed comment as a
0045  * \c CXComment_FullComment AST node.
0046  */
0047 CINDEX_LINKAGE CXComment clang_Cursor_getParsedComment(CXCursor C);
0048
0049 /**
0050  * Describes the type of the comment AST node (\c CXComment).  A comment
0051  * node can be considered block content (e. g., paragraph), inline content
0052  * (plain text) or neither (the root AST node).
0053  */
0054 enum CXCommentKind {
0055   /**
0056    * Null comment.  No AST node is constructed at the requested location
0057    * because there is no text or a syntax error.
0058    */
0059   CXComment_Null = 0,
0060
0061   /**
0062    * Plain text.  Inline content.
0063    */
0064   CXComment_Text = 1,
0065
0066   /**
0067    * A command with word-like arguments that is considered inline content.
0068    *
0069    * For example: \\c command.
0070    */
0071   CXComment_InlineCommand = 2,
0072
0073   /**
0074    * HTML start tag with attributes (name-value pairs).  Considered
0075    * inline content.
0076    *
0077    * For example:
0078    * \verbatim
0079    * <br> <br /> <a href="http://example.org/">
0080    * \endverbatim
0081    */
0082   CXComment_HTMLStartTag = 3,
0083
0084   /**
0085    * HTML end tag.  Considered inline content.
0086    *
0087    * For example:
0088    * \verbatim
0089    * </a>
0090    * \endverbatim
0091    */
0092   CXComment_HTMLEndTag = 4,
0093
0094   /**
0095    * A paragraph, contains inline comment.  The paragraph itself is
0096    * block content.
0097    */
0098   CXComment_Paragraph = 5,
0099
0100   /**
0101    * A command that has zero or more word-like arguments (number of
0102    * word-like arguments depends on command name) and a paragraph as an
0103    * argument.  Block command is block content.
0104    *
0105    * Paragraph argument is also a child of the block command.
0106    *
0107    * For example: \has 0 word-like arguments and a paragraph argument.
0108    *
0109    * AST nodes of special kinds that parser knows about (e. g., \\param
0110    * command) have their own node kinds.
0111    */
0112   CXComment_BlockCommand = 6,
0113
0114   /**
0115    * A \\param or \\arg command that describes the function parameter
0116    * (name, passing direction, description).
0117    *
0118    * For example: \\param [in] ParamName description.
0119    */
0120   CXComment_ParamCommand = 7,
0121
0122   /**
0123    * A \\tparam command that describes a template parameter (name and
0124    * description).
0125    *
0126    * For example: \\tparam T description.
0127    */
0128   CXComment_TParamCommand = 8,
0129
0130   /**
0131    * A verbatim block command (e. g., preformatted code).  Verbatim
0132    * block has an opening and a closing command and contains multiple lines of
0133    * text (\c CXComment_VerbatimBlockLine child nodes).
0134    *
0135    * For example:
0136    * \\verbatim
0137    * aaa
0138    * \\endverbatim
0139    */
0140   CXComment_VerbatimBlockCommand = 9,
0141
0142   /**
0143    * A line of text that is contained within a
0144    * CXComment_VerbatimBlockCommand node.
0145    */
0146   CXComment_VerbatimBlockLine = 10,
0147
0148   /**
0149    * A verbatim line command.  Verbatim line has an opening command,
0150    * a single line of text (up to the newline after the opening command) and
0151    * has no closing command.
0152    */
0153   CXComment_VerbatimLine = 11,
0154
0155   /**
0156    * A full comment attached to a declaration, contains block content.
0157    */
0158   CXComment_FullComment = 12
0159 };
0160
0161 /**
0162  * The most appropriate rendering mode for an inline command, chosen on
0163  * command semantics in Doxygen.
0164  */
0165 enum CXCommentInlineCommandRenderKind {
0166   /**
0167    * Command argument should be rendered in a normal font.
0168    */
0169   CXCommentInlineCommandRenderKind_Normal,
0170
0171   /**
0172    * Command argument should be rendered in a bold font.
0173    */
0174   CXCommentInlineCommandRenderKind_Bold,
0175
0176   /**
0177    * Command argument should be rendered in a monospaced font.
0178    */
0179   CXCommentInlineCommandRenderKind_Monospaced,
0180
0181   /**
0182    * Command argument should be rendered emphasized (typically italic
0183    * font).
0184    */
0185   CXCommentInlineCommandRenderKind_Emphasized,
0186
0187   /**
0188    * Command argument should not be rendered (since it only defines an anchor).
0189    */
0190   CXCommentInlineCommandRenderKind_Anchor
0191 };
0192
0193 /**
0194  * Describes parameter passing direction for \\param or \\arg command.
0195  */
0196 enum CXCommentParamPassDirection {
0197   /**
0198    * The parameter is an input parameter.
0199    */
0200   CXCommentParamPassDirection_In,
0201
0202   /**
0203    * The parameter is an output parameter.
0204    */
0205   CXCommentParamPassDirection_Out,
0206
0207   /**
0208    * The parameter is an input and output parameter.
0209    */
0210   CXCommentParamPassDirection_InOut
0211 };
0212
0213 /**
0214  * \param Comment AST node of any kind.
0215  *
0216  * \returns the type of the AST node.
0217  */
0218 CINDEX_LINKAGE enum CXCommentKind clang_Comment_getKind(CXComment Comment);
0219
0220 /**
0221  * \param Comment AST node of any kind.
0222  *
0223  * \returns number of children of the AST node.
0224  */
0225 CINDEX_LINKAGE unsigned clang_Comment_getNumChildren(CXComment Comment);
0226
0227 /**
0228  * \param Comment AST node of any kind.
0229  *
0230  * \param ChildIdx child index (zero-based).
0231  *
0232  * \returns the specified child of the AST node.
0233  */
0234 CINDEX_LINKAGE
0235 CXComment clang_Comment_getChild(CXComment Comment, unsigned ChildIdx);
0236
0237 /**
0238  * A \c CXComment_Paragraph node is considered whitespace if it contains
0239  * only \c CXComment_Text nodes that are empty or whitespace.
0240  *
0241  * Other AST nodes (except \c CXComment_Paragraph and \c CXComment_Text) are
0242  * never considered whitespace.
0243  *
0244  * \returns non-zero if \c Comment is whitespace.
0245  */
0246 CINDEX_LINKAGE unsigned clang_Comment_isWhitespace(CXComment Comment);
0247
0248 /**
0249  * \returns non-zero if \c Comment is inline content and has a newline
0250  * immediately following it in the comment text.  Newlines between paragraphs
0251  * do not count.
0252  */
0253 CINDEX_LINKAGE
0254 unsigned clang_InlineContentComment_hasTrailingNewline(CXComment Comment);
0255
0256 /**
0257  * \param Comment a \c CXComment_Text AST node.
0258  *
0259  * \returns text contained in the AST node.
0260  */
0261 CINDEX_LINKAGE CXString clang_TextComment_getText(CXComment Comment);
0262
0263 /**
0264  * \param Comment a \c CXComment_InlineCommand AST node.
0265  *
0266  * \returns name of the inline command.
0267  */
0268 CINDEX_LINKAGE
0269 CXString clang_InlineCommandComment_getCommandName(CXComment Comment);
0270
0271 /**
0272  * \param Comment a \c CXComment_InlineCommand AST node.
0273  *
0274  * \returns the most appropriate rendering mode, chosen on command
0275  * semantics in Doxygen.
0276  */
0277 CINDEX_LINKAGE enum CXCommentInlineCommandRenderKind
0278 clang_InlineCommandComment_getRenderKind(CXComment Comment);
0279
0280 /**
0281  * \param Comment a \c CXComment_InlineCommand AST node.
0282  *
0283  * \returns number of command arguments.
0284  */
0285 CINDEX_LINKAGE
0286 unsigned clang_InlineCommandComment_getNumArgs(CXComment Comment);
0287
0288 /**
0289  * \param Comment a \c CXComment_InlineCommand AST node.
0290  *
0291  * \param ArgIdx argument index (zero-based).
0292  *
0293  * \returns text of the specified argument.
0294  */
0295 CINDEX_LINKAGE
0296 CXString clang_InlineCommandComment_getArgText(CXComment Comment,
0297                                                unsigned ArgIdx);
0298
0299 /**
0300  * \param Comment a \c CXComment_HTMLStartTag or \c CXComment_HTMLEndTag AST
0301  * node.
0302  *
0303  * \returns HTML tag name.
0304  */
0305 CINDEX_LINKAGE CXString clang_HTMLTagComment_getTagName(CXComment Comment);
0306
0307 /**
0308  * \param Comment a \c CXComment_HTMLStartTag AST node.
0309  *
0310  * \returns non-zero if tag is self-closing (for example, &lt;br /&gt;).
0311  */
0312 CINDEX_LINKAGE
0313 unsigned clang_HTMLStartTagComment_isSelfClosing(CXComment Comment);
0314
0315 /**
0316  * \param Comment a \c CXComment_HTMLStartTag AST node.
0317  *
0318  * \returns number of attributes (name-value pairs) attached to the start tag.
0319  */
0320 CINDEX_LINKAGE unsigned clang_HTMLStartTag_getNumAttrs(CXComment Comment);
0321
0322 /**
0323  * \param Comment a \c CXComment_HTMLStartTag AST node.
0324  *
0325  * \param AttrIdx attribute index (zero-based).
0326  *
0327  * \returns name of the specified attribute.
0328  */
0329 CINDEX_LINKAGE
0330 CXString clang_HTMLStartTag_getAttrName(CXComment Comment, unsigned AttrIdx);
0331
0332 /**
0333  * \param Comment a \c CXComment_HTMLStartTag AST node.
0334  *
0335  * \param AttrIdx attribute index (zero-based).
0336  *
0337  * \returns value of the specified attribute.
0338  */
0339 CINDEX_LINKAGE
0340 CXString clang_HTMLStartTag_getAttrValue(CXComment Comment, unsigned AttrIdx);
0341
0342 /**
0343  * \param Comment a \c CXComment_BlockCommand AST node.
0344  *
0345  * \returns name of the block command.
0346  */
0347 CINDEX_LINKAGE
0348 CXString clang_BlockCommandComment_getCommandName(CXComment Comment);
0349
0350 /**
0351  * \param Comment a \c CXComment_BlockCommand AST node.
0352  *
0353  * \returns number of word-like arguments.
0354  */
0355 CINDEX_LINKAGE
0356 unsigned clang_BlockCommandComment_getNumArgs(CXComment Comment);
0357
0358 /**
0359  * \param Comment a \c CXComment_BlockCommand AST node.
0360  *
0361  * \param ArgIdx argument index (zero-based).
0362  *
0363  * \returns text of the specified word-like argument.
0364  */
0365 CINDEX_LINKAGE
0366 CXString clang_BlockCommandComment_getArgText(CXComment Comment,
0367                                               unsigned ArgIdx);
0368
0369 /**
0370  * \param Comment a \c CXComment_BlockCommand or
0371  * \c CXComment_VerbatimBlockCommand AST node.
0372  *
0373  * \returns paragraph argument of the block command.
0374  */
0375 CINDEX_LINKAGE
0376 CXComment clang_BlockCommandComment_getParagraph(CXComment Comment);
0377
0378 /**
0379  * \param Comment a \c CXComment_ParamCommand AST node.
0380  *
0381  * \returns parameter name.
0382  */
0383 CINDEX_LINKAGE
0384 CXString clang_ParamCommandComment_getParamName(CXComment Comment);
0385
0386 /**
0387  * \param Comment a \c CXComment_ParamCommand AST node.
0388  *
0389  * \returns non-zero if the parameter that this AST node represents was found
0390  * in the function prototype and \c clang_ParamCommandComment_getParamIndex
0391  * function will return a meaningful value.
0392  */
0393 CINDEX_LINKAGE
0394 unsigned clang_ParamCommandComment_isParamIndexValid(CXComment Comment);
0395
0396 /**
0397  * \param Comment a \c CXComment_ParamCommand AST node.
0398  *
0399  * \returns zero-based parameter index in function prototype.
0400  */
0401 CINDEX_LINKAGE
0402 unsigned clang_ParamCommandComment_getParamIndex(CXComment Comment);
0403
0404 /**
0405  * \param Comment a \c CXComment_ParamCommand AST node.
0406  *
0407  * \returns non-zero if parameter passing direction was specified explicitly in
0408  * the comment.
0409  */
0410 CINDEX_LINKAGE
0411 unsigned clang_ParamCommandComment_isDirectionExplicit(CXComment Comment);
0412
0413 /**
0414  * \param Comment a \c CXComment_ParamCommand AST node.
0415  *
0416  * \returns parameter passing direction.
0417  */
0418 CINDEX_LINKAGE
0419 enum CXCommentParamPassDirection clang_ParamCommandComment_getDirection(
0420                                                             CXComment Comment);
0421
0422 /**
0423  * \param Comment a \c CXComment_TParamCommand AST node.
0424  *
0425  * \returns template parameter name.
0426  */
0427 CINDEX_LINKAGE
0428 CXString clang_TParamCommandComment_getParamName(CXComment Comment);
0429
0430 /**
0431  * \param Comment a \c CXComment_TParamCommand AST node.
0432  *
0433  * \returns non-zero if the parameter that this AST node represents was found
0434  * in the template parameter list and
0435  * \c clang_TParamCommandComment_getDepth and
0436  * \c clang_TParamCommandComment_getIndex functions will return a meaningful
0437  * value.
0438  */
0439 CINDEX_LINKAGE
0440 unsigned clang_TParamCommandComment_isParamPositionValid(CXComment Comment);
0441
0442 /**
0443  * \param Comment a \c CXComment_TParamCommand AST node.
0444  *
0445  * \returns zero-based nesting depth of this parameter in the template parameter list.
0446  *
0447  * For example,
0448  * \verbatim
0449  *     template<typename C, template<typename T> class TT>
0450  *     void test(TT<int> aaa);
0451  * \endverbatim
0452  * for C and TT nesting depth is 0,
0453  * for T nesting depth is 1.
0454  */
0455 CINDEX_LINKAGE
0456 unsigned clang_TParamCommandComment_getDepth(CXComment Comment);
0457
0458 /**
0459  * \param Comment a \c CXComment_TParamCommand AST node.
0460  *
0461  * \returns zero-based parameter index in the template parameter list at a
0462  * given nesting depth.
0463  *
0464  * For example,
0465  * \verbatim
0466  *     template<typename C, template<typename T> class TT>
0467  *     void test(TT<int> aaa);
0468  * \endverbatim
0469  * for C and TT nesting depth is 0, so we can ask for index at depth 0:
0470  * at depth 0 C's index is 0, TT's index is 1.
0471  *
0472  * For T nesting depth is 1, so we can ask for index at depth 0 and 1:
0473  * at depth 0 T's index is 1 (same as TT's),
0474  * at depth 1 T's index is 0.
0475  */
0476 CINDEX_LINKAGE
0477 unsigned clang_TParamCommandComment_getIndex(CXComment Comment, unsigned Depth);
0478
0479 /**
0480  * \param Comment a \c CXComment_VerbatimBlockLine AST node.
0481  *
0482  * \returns text contained in the AST node.
0483  */
0484 CINDEX_LINKAGE
0485 CXString clang_VerbatimBlockLineComment_getText(CXComment Comment);
0486
0487 /**
0488  * \param Comment a \c CXComment_VerbatimLine AST node.
0489  *
0490  * \returns text contained in the AST node.
0491  */
0492 CINDEX_LINKAGE CXString clang_VerbatimLineComment_getText(CXComment Comment);
0493
0494 /**
0495  * Convert an HTML tag AST node to string.
0496  *
0497  * \param Comment a \c CXComment_HTMLStartTag or \c CXComment_HTMLEndTag AST
0498  * node.
0499  *
0500  * \returns string containing an HTML tag.
0501  */
0502 CINDEX_LINKAGE CXString clang_HTMLTagComment_getAsString(CXComment Comment);
0503
0504 /**
0505  * Convert a given full parsed comment to an HTML fragment.
0506  *
0507  * Specific details of HTML layout are subject to change.  Don't try to parse
0508  * this HTML back into an AST, use other APIs instead.
0509  *
0510  * Currently the following CSS classes are used:
0511  * \li "para-brief" for \paragraph and equivalent commands;
0512  * \li "para-returns" for \\returns paragraph and equivalent commands;
0513  * \li "word-returns" for the "Returns" word in \\returns paragraph.
0514  *
0515  * Function argument documentation is rendered as a \<dl\> list with arguments
0516  * sorted in function prototype order.  CSS classes used:
0517  * \li "param-name-index-NUMBER" for parameter name (\<dt\>);
0518  * \li "param-descr-index-NUMBER" for parameter description (\<dd\>);
0519  * \li "param-name-index-invalid" and "param-descr-index-invalid" are used if
0520  * parameter index is invalid.
0521  *
0522  * Template parameter documentation is rendered as a \<dl\> list with
0523  * parameters sorted in template parameter list order.  CSS classes used:
0524  * \li "tparam-name-index-NUMBER" for parameter name (\<dt\>);
0525  * \li "tparam-descr-index-NUMBER" for parameter description (\<dd\>);
0526  * \li "tparam-name-index-other" and "tparam-descr-index-other" are used for
0527  * names inside template template parameters;
0528  * \li "tparam-name-index-invalid" and "tparam-descr-index-invalid" are used if
0529  * parameter position is invalid.
0530  *
0531  * \param Comment a \c CXComment_FullComment AST node.
0532  *
0533  * \returns string containing an HTML fragment.
0534  */
0535 CINDEX_LINKAGE CXString clang_FullComment_getAsHTML(CXComment Comment);
0536
0537 /**
0538  * Convert a given full parsed comment to an XML document.
0539  *
0540  * A Relax NG schema for the XML can be found in comment-xml-schema.rng file
0541  * inside clang source tree.
0542  *
0543  * \param Comment a \c CXComment_FullComment AST node.
0544  *
0545  * \returns string containing an XML document.
0546  */
0547 CINDEX_LINKAGE CXString clang_FullComment_getAsXML(CXComment Comment);
0548
0549 /**
0550  * CXAPISet is an opaque type that represents a data structure containing all
0551  * the API information for a given translation unit. This can be used for a
0552  * single symbol symbol graph for a given symbol.
0553  */
0554 typedef struct CXAPISetImpl *CXAPISet;
0555
0556 /**
0557  * Traverses the translation unit to create a \c CXAPISet.
0558  *
0559  * \param tu is the \c CXTranslationUnit to build the \c CXAPISet for.
0560  *
0561  * \param out_api is a pointer to the output of this function. It is needs to be
0562  * disposed of by calling clang_disposeAPISet.
0563  *
0564  * \returns Error code indicating success or failure of the APISet creation.
0565  */
0566 CINDEX_LINKAGE enum CXErrorCode clang_createAPISet(CXTranslationUnit tu,
0567                                                    CXAPISet *out_api);
0568
0569 /**
0570  * Dispose of an APISet.
0571  *
0572  * The provided \c CXAPISet can not be used after this function is called.
0573  */
0574 CINDEX_LINKAGE void clang_disposeAPISet(CXAPISet api);
0575
0576 /**
0577  * Generate a single symbol symbol graph for the given USR. Returns a null
0578  * string if the associated symbol can not be found in the provided \c CXAPISet.
0579  *
0580  * The output contains the symbol graph as well as some additional information
0581  * about related symbols.
0582  *
0583  * \param usr is a string containing the USR of the symbol to generate the
0584  * symbol graph for.
0585  *
0586  * \param api the \c CXAPISet to look for the symbol in.
0587  *
0588  * \returns a string containing the serialized symbol graph representation for
0589  * the symbol being queried or a null string if it can not be found in the
0590  * APISet.
0591  */
0592 CINDEX_LINKAGE CXString clang_getSymbolGraphForUSR(const char *usr,
0593                                                    CXAPISet api);
0594
0595 /**
0596  * Generate a single symbol symbol graph for the declaration at the given
0597  * cursor. Returns a null string if the AST node for the cursor isn't a
0598  * declaration.
0599  *
0600  * The output contains the symbol graph as well as some additional information
0601  * about related symbols.
0602  *
0603  * \param cursor the declaration for which to generate the single symbol symbol
0604  * graph.
0605  *
0606  * \returns a string containing the serialized symbol graph representation for
0607  * the symbol being queried or a null string if it can not be found in the
0608  * APISet.
0609  */
0610 CINDEX_LINKAGE CXString clang_getSymbolGraphForCursor(CXCursor cursor);
0611
0612 /**
0613  * @}
0614  */
0615
0616 LLVM_CLANG_C_EXTERN_C_END
0617
0618 #endif /* CLANG_C_DOCUMENTATION_H */
0619