diff options
Diffstat (limited to 'contrib/llvm/tools/clang/include/clang-c/Index.h')
| -rw-r--r-- | contrib/llvm/tools/clang/include/clang-c/Index.h | 1658 |
1 files changed, 948 insertions, 710 deletions
diff --git a/contrib/llvm/tools/clang/include/clang-c/Index.h b/contrib/llvm/tools/clang/include/clang-c/Index.h index 587008a7210b..0ad90010ccd9 100644 --- a/contrib/llvm/tools/clang/include/clang-c/Index.h +++ b/contrib/llvm/tools/clang/include/clang-c/Index.h @@ -24,7 +24,7 @@ #include "clang-c/BuildSystem.h" /** - * \brief The version constants for the libclang API. + * The version constants for the libclang API. * CINDEX_VERSION_MINOR should increase when there are API additions. * CINDEX_VERSION_MAJOR is intended for "major" source/ABI breaking changes. * @@ -32,7 +32,7 @@ * compatible, thus CINDEX_VERSION_MAJOR is expected to remain stable. */ #define CINDEX_VERSION_MAJOR 0 -#define CINDEX_VERSION_MINOR 45 +#define CINDEX_VERSION_MINOR 49 #define CINDEX_VERSION_ENCODE(major, minor) ( \ ((major) * 10000) \ @@ -75,30 +75,30 @@ extern "C" { */ /** - * \brief An "index" that consists of a set of translation units that would + * An "index" that consists of a set of translation units that would * typically be linked together into an executable or library. */ typedef void *CXIndex; /** - * \brief An opaque type representing target information for a given translation + * An opaque type representing target information for a given translation * unit. */ typedef struct CXTargetInfoImpl *CXTargetInfo; /** - * \brief A single translation unit, which resides in an index. + * A single translation unit, which resides in an index. */ typedef struct CXTranslationUnitImpl *CXTranslationUnit; /** - * \brief Opaque pointer representing client data that will be passed through + * Opaque pointer representing client data that will be passed through * to various callbacks and visitors. */ typedef void *CXClientData; /** - * \brief Provides the contents of a file that has not yet been saved to disk. + * Provides the contents of a file that has not yet been saved to disk. * * Each CXUnsavedFile instance provides the name of a file on the * system along with the current contents of that file that have not @@ -106,66 +106,66 @@ typedef void *CXClientData; */ struct CXUnsavedFile { /** - * \brief The file whose contents have not yet been saved. + * The file whose contents have not yet been saved. * * This file must already exist in the file system. */ const char *Filename; /** - * \brief A buffer containing the unsaved contents of this file. + * A buffer containing the unsaved contents of this file. */ const char *Contents; /** - * \brief The length of the unsaved contents of this buffer. + * The length of the unsaved contents of this buffer. */ unsigned long Length; }; /** - * \brief Describes the availability of a particular entity, which indicates + * Describes the availability of a particular entity, which indicates * whether the use of this entity will result in a warning or error due to * it being deprecated or unavailable. */ enum CXAvailabilityKind { /** - * \brief The entity is available. + * The entity is available. */ CXAvailability_Available, /** - * \brief The entity is available, but has been deprecated (and its use is + * The entity is available, but has been deprecated (and its use is * not recommended). */ CXAvailability_Deprecated, /** - * \brief The entity is not available; any use of it will be an error. + * The entity is not available; any use of it will be an error. */ CXAvailability_NotAvailable, /** - * \brief The entity is available, but not accessible; any use of it will be + * The entity is available, but not accessible; any use of it will be * an error. */ CXAvailability_NotAccessible }; /** - * \brief Describes a version number of the form major.minor.subminor. + * Describes a version number of the form major.minor.subminor. */ typedef struct CXVersion { /** - * \brief The major version number, e.g., the '10' in '10.7.3'. A negative + * The major version number, e.g., the '10' in '10.7.3'. A negative * value indicates that there is no version number at all. */ int Major; /** - * \brief The minor version number, e.g., the '7' in '10.7.3'. This value + * The minor version number, e.g., the '7' in '10.7.3'. This value * will be negative if no minor version number was provided, e.g., for * version '10'. */ int Minor; /** - * \brief The subminor version number, e.g., the '3' in '10.7.3'. This value + * The subminor version number, e.g., the '3' in '10.7.3'. This value * will be negative if no minor or subminor version number was provided, * e.g., in version '10' or '10.7'. */ @@ -173,60 +173,60 @@ typedef struct CXVersion { } CXVersion; /** - * \brief Describes the exception specification of a cursor. + * Describes the exception specification of a cursor. * * A negative value indicates that the cursor is not a function declaration. */ enum CXCursor_ExceptionSpecificationKind { /** - * \brief The cursor has no exception specification. + * The cursor has no exception specification. */ CXCursor_ExceptionSpecificationKind_None, /** - * \brief The cursor has exception specification throw() + * The cursor has exception specification throw() */ CXCursor_ExceptionSpecificationKind_DynamicNone, /** - * \brief The cursor has exception specification throw(T1, T2) + * The cursor has exception specification throw(T1, T2) */ CXCursor_ExceptionSpecificationKind_Dynamic, /** - * \brief The cursor has exception specification throw(...). + * The cursor has exception specification throw(...). */ CXCursor_ExceptionSpecificationKind_MSAny, /** - * \brief The cursor has exception specification basic noexcept. + * The cursor has exception specification basic noexcept. */ CXCursor_ExceptionSpecificationKind_BasicNoexcept, /** - * \brief The cursor has exception specification computed noexcept. + * The cursor has exception specification computed noexcept. */ CXCursor_ExceptionSpecificationKind_ComputedNoexcept, /** - * \brief The exception specification has not yet been evaluated. + * The exception specification has not yet been evaluated. */ CXCursor_ExceptionSpecificationKind_Unevaluated, /** - * \brief The exception specification has not yet been instantiated. + * The exception specification has not yet been instantiated. */ CXCursor_ExceptionSpecificationKind_Uninstantiated, /** - * \brief The exception specification has not been parsed yet. + * The exception specification has not been parsed yet. */ CXCursor_ExceptionSpecificationKind_Unparsed }; /** - * \brief Provides a shared context for creating translation units. + * Provides a shared context for creating translation units. * * It provides two options: * @@ -269,7 +269,7 @@ CINDEX_LINKAGE CXIndex clang_createIndex(int excludeDeclarationsFromPCH, int displayDiagnostics); /** - * \brief Destroy the given index. + * Destroy the given index. * * The index must not be destroyed until all of the translation units created * within that index have been destroyed. @@ -278,12 +278,12 @@ CINDEX_LINKAGE void clang_disposeIndex(CXIndex index); typedef enum { /** - * \brief Used to indicate that no special CXIndex options are needed. + * Used to indicate that no special CXIndex options are needed. */ CXGlobalOpt_None = 0x0, /** - * \brief Used to indicate that threads that libclang creates for indexing + * Used to indicate that threads that libclang creates for indexing * purposes should use background priority. * * Affects #clang_indexSourceFile, #clang_indexTranslationUnit, @@ -292,7 +292,7 @@ typedef enum { CXGlobalOpt_ThreadBackgroundPriorityForIndexing = 0x1, /** - * \brief Used to indicate that threads that libclang creates for editing + * Used to indicate that threads that libclang creates for editing * purposes should use background priority. * * Affects #clang_reparseTranslationUnit, #clang_codeCompleteAt, @@ -301,7 +301,7 @@ typedef enum { CXGlobalOpt_ThreadBackgroundPriorityForEditing = 0x2, /** - * \brief Used to indicate that all threads that libclang creates should use + * Used to indicate that all threads that libclang creates should use * background priority. */ CXGlobalOpt_ThreadBackgroundPriorityForAll = @@ -311,7 +311,7 @@ typedef enum { } CXGlobalOptFlags; /** - * \brief Sets general options associated with a CXIndex. + * Sets general options associated with a CXIndex. * * For example: * \code @@ -326,7 +326,7 @@ typedef enum { CINDEX_LINKAGE void clang_CXIndex_setGlobalOptions(CXIndex, unsigned options); /** - * \brief Gets the general options associated with a CXIndex. + * Gets the general options associated with a CXIndex. * * \returns A bitmask of options, a bitwise OR of CXGlobalOpt_XXX flags that * are associated with the given CXIndex object. @@ -334,7 +334,7 @@ CINDEX_LINKAGE void clang_CXIndex_setGlobalOptions(CXIndex, unsigned options); CINDEX_LINKAGE unsigned clang_CXIndex_getGlobalOptions(CXIndex); /** - * \brief Sets the invocation emission path option in a CXIndex. + * Sets the invocation emission path option in a CXIndex. * * The invocation emission path specifies a path which will contain log * files for certain libclang invocations. A null value (default) implies that @@ -350,22 +350,22 @@ clang_CXIndex_setInvocationEmissionPathOption(CXIndex, const char *Path); */ /** - * \brief A particular source file that is part of a translation unit. + * A particular source file that is part of a translation unit. */ typedef void *CXFile; /** - * \brief Retrieve the complete file and path name of the given file. + * Retrieve the complete file and path name of the given file. */ CINDEX_LINKAGE CXString clang_getFileName(CXFile SFile); /** - * \brief Retrieve the last modification time of the given file. + * Retrieve the last modification time of the given file. */ CINDEX_LINKAGE time_t clang_getFileTime(CXFile SFile); /** - * \brief Uniquely identifies a CXFile, that refers to the same underlying file, + * Uniquely identifies a CXFile, that refers to the same underlying file, * across an indexing session. */ typedef struct { @@ -373,7 +373,7 @@ typedef struct { } CXFileUniqueID; /** - * \brief Retrieve the unique ID for the given \c file. + * Retrieve the unique ID for the given \c file. * * \param file the file to get the ID for. * \param outID stores the returned CXFileUniqueID. @@ -383,7 +383,7 @@ typedef struct { CINDEX_LINKAGE int clang_getFileUniqueID(CXFile file, CXFileUniqueID *outID); /** - * \brief Determine whether the given header is guarded against + * Determine whether the given header is guarded against * multiple inclusions, either with the conventional * \#ifndef/\#define/\#endif macro guards or with \#pragma once. */ @@ -391,7 +391,7 @@ CINDEX_LINKAGE unsigned clang_isFileMultipleIncludeGuarded(CXTranslationUnit tu, CXFile file); /** - * \brief Retrieve a file handle within the given translation unit. + * Retrieve a file handle within the given translation unit. * * \param tu the translation unit * @@ -404,7 +404,7 @@ CINDEX_LINKAGE CXFile clang_getFile(CXTranslationUnit tu, const char *file_name); /** - * \brief Retrieve the buffer associated with the given file. + * Retrieve the buffer associated with the given file. * * \param tu the translation unit * @@ -419,12 +419,19 @@ CINDEX_LINKAGE const char *clang_getFileContents(CXTranslationUnit tu, CXFile file, size_t *size); /** - * \brief Returns non-zero if the \c file1 and \c file2 point to the same file, + * Returns non-zero if the \c file1 and \c file2 point to the same file, * or they are both NULL. */ CINDEX_LINKAGE int clang_File_isEqual(CXFile file1, CXFile file2); /** + * Returns the real path name of \c file. + * + * An empty string may be returned. Use \c clang_getFileName() in that case. + */ +CINDEX_LINKAGE CXString clang_File_tryGetRealPathName(CXFile file); + +/** * @} */ @@ -442,7 +449,7 @@ CINDEX_LINKAGE int clang_File_isEqual(CXFile file1, CXFile file2); */ /** - * \brief Identifies a specific source location within a translation + * Identifies a specific source location within a translation * unit. * * Use clang_getExpansionLocation() or clang_getSpellingLocation() @@ -454,7 +461,7 @@ typedef struct { } CXSourceLocation; /** - * \brief Identifies a half-open character range in the source code. + * Identifies a half-open character range in the source code. * * Use clang_getRangeStart() and clang_getRangeEnd() to retrieve the * starting and end locations from a source range, respectively. @@ -466,12 +473,12 @@ typedef struct { } CXSourceRange; /** - * \brief Retrieve a NULL (invalid) source location. + * Retrieve a NULL (invalid) source location. */ CINDEX_LINKAGE CXSourceLocation clang_getNullLocation(void); /** - * \brief Determine whether two source locations, which must refer into + * Determine whether two source locations, which must refer into * the same translation unit, refer to exactly the same point in the source * code. * @@ -482,7 +489,7 @@ CINDEX_LINKAGE unsigned clang_equalLocations(CXSourceLocation loc1, CXSourceLocation loc2); /** - * \brief Retrieves the source location associated with a given file/line/column + * Retrieves the source location associated with a given file/line/column * in a particular translation unit. */ CINDEX_LINKAGE CXSourceLocation clang_getLocation(CXTranslationUnit tu, @@ -490,7 +497,7 @@ CINDEX_LINKAGE CXSourceLocation clang_getLocation(CXTranslationUnit tu, unsigned line, unsigned column); /** - * \brief Retrieves the source location associated with a given character offset + * Retrieves the source location associated with a given character offset * in a particular translation unit. */ CINDEX_LINKAGE CXSourceLocation clang_getLocationForOffset(CXTranslationUnit tu, @@ -498,30 +505,30 @@ CINDEX_LINKAGE CXSourceLocation clang_getLocationForOffset(CXTranslationUnit tu, unsigned offset); /** - * \brief Returns non-zero if the given source location is in a system header. + * Returns non-zero if the given source location is in a system header. */ CINDEX_LINKAGE int clang_Location_isInSystemHeader(CXSourceLocation location); /** - * \brief Returns non-zero if the given source location is in the main file of + * Returns non-zero if the given source location is in the main file of * the corresponding translation unit. */ CINDEX_LINKAGE int clang_Location_isFromMainFile(CXSourceLocation location); /** - * \brief Retrieve a NULL (invalid) source range. + * Retrieve a NULL (invalid) source range. */ CINDEX_LINKAGE CXSourceRange clang_getNullRange(void); /** - * \brief Retrieve a source range given the beginning and ending source + * Retrieve a source range given the beginning and ending source * locations. */ CINDEX_LINKAGE CXSourceRange clang_getRange(CXSourceLocation begin, CXSourceLocation end); /** - * \brief Determine whether two ranges are equivalent. + * Determine whether two ranges are equivalent. * * \returns non-zero if the ranges are the same, zero if they differ. */ @@ -529,12 +536,12 @@ CINDEX_LINKAGE unsigned clang_equalRanges(CXSourceRange range1, CXSourceRange range2); /** - * \brief Returns non-zero if \p range is null. + * Returns non-zero if \p range is null. */ CINDEX_LINKAGE int clang_Range_isNull(CXSourceRange range); /** - * \brief Retrieve the file, line, column, and offset represented by + * Retrieve the file, line, column, and offset represented by * the given source location. * * If the location refers into a macro expansion, retrieves the @@ -562,7 +569,7 @@ CINDEX_LINKAGE void clang_getExpansionLocation(CXSourceLocation location, unsigned *offset); /** - * \brief Retrieve the file, line and column represented by the given source + * Retrieve the file, line and column represented by the given source * location, as specified in a # line directive. * * Example: given the following source code in a file somefile.c @@ -607,7 +614,7 @@ CINDEX_LINKAGE void clang_getPresumedLocation(CXSourceLocation location, unsigned *column); /** - * \brief Legacy API to retrieve the file, line, column, and offset represented + * Legacy API to retrieve the file, line, column, and offset represented * by the given source location. * * This interface has been replaced by the newer interface @@ -621,7 +628,7 @@ CINDEX_LINKAGE void clang_getInstantiationLocation(CXSourceLocation location, unsigned *offset); /** - * \brief Retrieve the file, line, column, and offset represented by + * Retrieve the file, line, column, and offset represented by * the given source location. * * If the location refers into a macro instantiation, return where the @@ -649,7 +656,7 @@ CINDEX_LINKAGE void clang_getSpellingLocation(CXSourceLocation location, unsigned *offset); /** - * \brief Retrieve the file, line, column, and offset represented by + * Retrieve the file, line, column, and offset represented by * the given source location. * * If the location refers into a macro expansion, return where the macro was @@ -678,31 +685,31 @@ CINDEX_LINKAGE void clang_getFileLocation(CXSourceLocation location, unsigned *offset); /** - * \brief Retrieve a source location representing the first character within a + * Retrieve a source location representing the first character within a * source range. */ CINDEX_LINKAGE CXSourceLocation clang_getRangeStart(CXSourceRange range); /** - * \brief Retrieve a source location representing the last character within a + * Retrieve a source location representing the last character within a * source range. */ CINDEX_LINKAGE CXSourceLocation clang_getRangeEnd(CXSourceRange range); /** - * \brief Identifies an array of ranges. + * Identifies an array of ranges. */ typedef struct { - /** \brief The number of ranges in the \c ranges array. */ + /** The number of ranges in the \c ranges array. */ unsigned count; /** - * \brief An array of \c CXSourceRanges. + * An array of \c CXSourceRanges. */ CXSourceRange *ranges; } CXSourceRangeList; /** - * \brief Retrieve all ranges that were skipped by the preprocessor. + * Retrieve all ranges that were skipped by the preprocessor. * * The preprocessor will skip lines when they are surrounded by an * if/ifdef/ifndef directive whose condition does not evaluate to true. @@ -711,7 +718,7 @@ CINDEX_LINKAGE CXSourceRangeList *clang_getSkippedRanges(CXTranslationUnit tu, CXFile file); /** - * \brief Retrieve all ranges from all files that were skipped by the + * Retrieve all ranges from all files that were skipped by the * preprocessor. * * The preprocessor will skip lines when they are surrounded by an @@ -720,7 +727,7 @@ CINDEX_LINKAGE CXSourceRangeList *clang_getSkippedRanges(CXTranslationUnit tu, CINDEX_LINKAGE CXSourceRangeList *clang_getAllSkippedRanges(CXTranslationUnit tu); /** - * \brief Destroy the given \c CXSourceRangeList. + * Destroy the given \c CXSourceRangeList. */ CINDEX_LINKAGE void clang_disposeSourceRangeList(CXSourceRangeList *ranges); @@ -735,34 +742,34 @@ CINDEX_LINKAGE void clang_disposeSourceRangeList(CXSourceRangeList *ranges); */ /** - * \brief Describes the severity of a particular diagnostic. + * Describes the severity of a particular diagnostic. */ enum CXDiagnosticSeverity { /** - * \brief A diagnostic that has been suppressed, e.g., by a command-line + * A diagnostic that has been suppressed, e.g., by a command-line * option. */ CXDiagnostic_Ignored = 0, /** - * \brief This diagnostic is a note that should be attached to the + * This diagnostic is a note that should be attached to the * previous (non-note) diagnostic. */ CXDiagnostic_Note = 1, /** - * \brief This diagnostic indicates suspicious code that may not be + * This diagnostic indicates suspicious code that may not be * wrong. */ CXDiagnostic_Warning = 2, /** - * \brief This diagnostic indicates that the code is ill-formed. + * This diagnostic indicates that the code is ill-formed. */ CXDiagnostic_Error = 3, /** - * \brief This diagnostic indicates that the code is ill-formed such + * This diagnostic indicates that the code is ill-formed such * that future parser recovery is unlikely to produce useful * results. */ @@ -770,23 +777,23 @@ enum CXDiagnosticSeverity { }; /** - * \brief A single diagnostic, containing the diagnostic's severity, + * A single diagnostic, containing the diagnostic's severity, * location, text, source ranges, and fix-it hints. */ typedef void *CXDiagnostic; /** - * \brief A group of CXDiagnostics. + * A group of CXDiagnostics. */ typedef void *CXDiagnosticSet; /** - * \brief Determine the number of diagnostics in a CXDiagnosticSet. + * Determine the number of diagnostics in a CXDiagnosticSet. */ CINDEX_LINKAGE unsigned clang_getNumDiagnosticsInSet(CXDiagnosticSet Diags); /** - * \brief Retrieve a diagnostic associated with the given CXDiagnosticSet. + * Retrieve a diagnostic associated with the given CXDiagnosticSet. * * \param Diags the CXDiagnosticSet to query. * \param Index the zero-based diagnostic number to retrieve. @@ -798,36 +805,36 @@ CINDEX_LINKAGE CXDiagnostic clang_getDiagnosticInSet(CXDiagnosticSet Diags, unsigned Index); /** - * \brief Describes the kind of error that occurred (if any) in a call to + * Describes the kind of error that occurred (if any) in a call to * \c clang_loadDiagnostics. */ enum CXLoadDiag_Error { /** - * \brief Indicates that no error occurred. + * Indicates that no error occurred. */ CXLoadDiag_None = 0, /** - * \brief Indicates that an unknown error occurred while attempting to + * Indicates that an unknown error occurred while attempting to * deserialize diagnostics. */ CXLoadDiag_Unknown = 1, /** - * \brief Indicates that the file containing the serialized diagnostics + * Indicates that the file containing the serialized diagnostics * could not be opened. */ CXLoadDiag_CannotLoad = 2, /** - * \brief Indicates that the serialized diagnostics file is invalid or + * Indicates that the serialized diagnostics file is invalid or * corrupt. */ CXLoadDiag_InvalidFile = 3 }; /** - * \brief Deserialize a set of diagnostics from a Clang diagnostics bitcode + * Deserialize a set of diagnostics from a Clang diagnostics bitcode * file. * * \param file The name of the file to deserialize. @@ -844,12 +851,12 @@ CINDEX_LINKAGE CXDiagnosticSet clang_loadDiagnostics(const char *file, CXString *errorString); /** - * \brief Release a CXDiagnosticSet and all of its contained diagnostics. + * Release a CXDiagnosticSet and all of its contained diagnostics. */ CINDEX_LINKAGE void clang_disposeDiagnosticSet(CXDiagnosticSet Diags); /** - * \brief Retrieve the child diagnostics of a CXDiagnostic. + * Retrieve the child diagnostics of a CXDiagnostic. * * This CXDiagnosticSet does not need to be released by * clang_disposeDiagnosticSet. @@ -857,13 +864,13 @@ CINDEX_LINKAGE void clang_disposeDiagnosticSet(CXDiagnosticSet Diags); CINDEX_LINKAGE CXDiagnosticSet clang_getChildDiagnostics(CXDiagnostic D); /** - * \brief Determine the number of diagnostics produced for the given + * Determine the number of diagnostics produced for the given * translation unit. */ CINDEX_LINKAGE unsigned clang_getNumDiagnostics(CXTranslationUnit Unit); /** - * \brief Retrieve a diagnostic associated with the given translation unit. + * Retrieve a diagnostic associated with the given translation unit. * * \param Unit the translation unit to query. * \param Index the zero-based diagnostic number to retrieve. @@ -875,7 +882,7 @@ CINDEX_LINKAGE CXDiagnostic clang_getDiagnostic(CXTranslationUnit Unit, unsigned Index); /** - * \brief Retrieve the complete set of diagnostics associated with a + * Retrieve the complete set of diagnostics associated with a * translation unit. * * \param Unit the translation unit to query. @@ -884,19 +891,19 @@ CINDEX_LINKAGE CXDiagnosticSet clang_getDiagnosticSetFromTU(CXTranslationUnit Unit); /** - * \brief Destroy a diagnostic. + * Destroy a diagnostic. */ CINDEX_LINKAGE void clang_disposeDiagnostic(CXDiagnostic Diagnostic); /** - * \brief Options to control the display of diagnostics. + * Options to control the display of diagnostics. * * The values in this enum are meant to be combined to customize the * behavior of \c clang_formatDiagnostic(). */ enum CXDiagnosticDisplayOptions { /** - * \brief Display the source-location information where the + * Display the source-location information where the * diagnostic was located. * * When set, diagnostics will be prefixed by the file, line, and @@ -911,7 +918,7 @@ enum CXDiagnosticDisplayOptions { CXDiagnostic_DisplaySourceLocation = 0x01, /** - * \brief If displaying the source-location information of the + * If displaying the source-location information of the * diagnostic, also include the column number. * * This option corresponds to the clang flag \c -fshow-column. @@ -919,7 +926,7 @@ enum CXDiagnosticDisplayOptions { CXDiagnostic_DisplayColumn = 0x02, /** - * \brief If displaying the source-location information of the + * If displaying the source-location information of the * diagnostic, also include information about source ranges in a * machine-parsable format. * @@ -929,7 +936,7 @@ enum CXDiagnosticDisplayOptions { CXDiagnostic_DisplaySourceRanges = 0x04, /** - * \brief Display the option name associated with this diagnostic, if any. + * Display the option name associated with this diagnostic, if any. * * The option name displayed (e.g., -Wconversion) will be placed in brackets * after the diagnostic text. This option corresponds to the clang flag @@ -938,7 +945,7 @@ enum CXDiagnosticDisplayOptions { CXDiagnostic_DisplayOption = 0x08, /** - * \brief Display the category number associated with this diagnostic, if any. + * Display the category number associated with this diagnostic, if any. * * The category number is displayed within brackets after the diagnostic text. * This option corresponds to the clang flag @@ -947,7 +954,7 @@ enum CXDiagnosticDisplayOptions { CXDiagnostic_DisplayCategoryId = 0x10, /** - * \brief Display the category name associated with this diagnostic, if any. + * Display the category name associated with this diagnostic, if any. * * The category name is displayed within brackets after the diagnostic text. * This option corresponds to the clang flag @@ -957,7 +964,7 @@ enum CXDiagnosticDisplayOptions { }; /** - * \brief Format the given diagnostic in a manner that is suitable for display. + * Format the given diagnostic in a manner that is suitable for display. * * This routine will format the given diagnostic to a string, rendering * the diagnostic according to the various options given. The @@ -975,7 +982,7 @@ CINDEX_LINKAGE CXString clang_formatDiagnostic(CXDiagnostic Diagnostic, unsigned Options); /** - * \brief Retrieve the set of display options most similar to the + * Retrieve the set of display options most similar to the * default behavior of the clang compiler. * * \returns A set of display options suitable for use with \c @@ -984,13 +991,13 @@ CINDEX_LINKAGE CXString clang_formatDiagnostic(CXDiagnostic Diagnostic, CINDEX_LINKAGE unsigned clang_defaultDiagnosticDisplayOptions(void); /** - * \brief Determine the severity of the given diagnostic. + * Determine the severity of the given diagnostic. */ CINDEX_LINKAGE enum CXDiagnosticSeverity clang_getDiagnosticSeverity(CXDiagnostic); /** - * \brief Retrieve the source location of the given diagnostic. + * Retrieve the source location of the given diagnostic. * * This location is where Clang would print the caret ('^') when * displaying the diagnostic on the command line. @@ -998,12 +1005,12 @@ clang_getDiagnosticSeverity(CXDiagnostic); CINDEX_LINKAGE CXSourceLocation clang_getDiagnosticLocation(CXDiagnostic); /** - * \brief Retrieve the text of the given diagnostic. + * Retrieve the text of the given diagnostic. */ CINDEX_LINKAGE CXString clang_getDiagnosticSpelling(CXDiagnostic); /** - * \brief Retrieve the name of the command-line option that enabled this + * Retrieve the name of the command-line option that enabled this * diagnostic. * * \param Diag The diagnostic to be queried. @@ -1018,7 +1025,7 @@ CINDEX_LINKAGE CXString clang_getDiagnosticOption(CXDiagnostic Diag, CXString *Disable); /** - * \brief Retrieve the category number for this diagnostic. + * Retrieve the category number for this diagnostic. * * Diagnostics can be categorized into groups along with other, related * diagnostics (e.g., diagnostics under the same warning flag). This routine @@ -1030,7 +1037,7 @@ CINDEX_LINKAGE CXString clang_getDiagnosticOption(CXDiagnostic Diag, CINDEX_LINKAGE unsigned clang_getDiagnosticCategory(CXDiagnostic); /** - * \brief Retrieve the name of a particular diagnostic category. This + * Retrieve the name of a particular diagnostic category. This * is now deprecated. Use clang_getDiagnosticCategoryText() * instead. * @@ -1043,20 +1050,20 @@ CINDEX_DEPRECATED CINDEX_LINKAGE CXString clang_getDiagnosticCategoryName(unsigned Category); /** - * \brief Retrieve the diagnostic category text for a given diagnostic. + * Retrieve the diagnostic category text for a given diagnostic. * * \returns The text of the given diagnostic category. */ CINDEX_LINKAGE CXString clang_getDiagnosticCategoryText(CXDiagnostic); /** - * \brief Determine the number of source ranges associated with the given + * Determine the number of source ranges associated with the given * diagnostic. */ CINDEX_LINKAGE unsigned clang_getDiagnosticNumRanges(CXDiagnostic); /** - * \brief Retrieve a source range associated with the diagnostic. + * Retrieve a source range associated with the diagnostic. * * A diagnostic's source ranges highlight important elements in the source * code. On the command line, Clang displays source ranges by @@ -1072,13 +1079,13 @@ CINDEX_LINKAGE CXSourceRange clang_getDiagnosticRange(CXDiagnostic Diagnostic, unsigned Range); /** - * \brief Determine the number of fix-it hints associated with the + * Determine the number of fix-it hints associated with the * given diagnostic. */ CINDEX_LINKAGE unsigned clang_getDiagnosticNumFixIts(CXDiagnostic Diagnostic); /** - * \brief Retrieve the replacement information for a given fix-it. + * Retrieve the replacement information for a given fix-it. * * Fix-its are described in terms of a source range whose contents * should be replaced by a string. This approach generalizes over @@ -1121,13 +1128,13 @@ CINDEX_LINKAGE CXString clang_getDiagnosticFixIt(CXDiagnostic Diagnostic, */ /** - * \brief Get the original translation unit source file name. + * Get the original translation unit source file name. */ CINDEX_LINKAGE CXString clang_getTranslationUnitSpelling(CXTranslationUnit CTUnit); /** - * \brief Return the CXTranslationUnit for a given source file and the provided + * Return the CXTranslationUnit for a given source file and the provided * command line arguments one would pass to the compiler. * * Note: The 'source_filename' argument is optional. If the caller provides a @@ -1175,7 +1182,7 @@ CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnitFromSourceFile( struct CXUnsavedFile *unsaved_files); /** - * \brief Same as \c clang_createTranslationUnit2, but returns + * Same as \c clang_createTranslationUnit2, but returns * the \c CXTranslationUnit instead of an error code. In case of an error this * routine returns a \c NULL \c CXTranslationUnit, without further detailed * error codes. @@ -1185,7 +1192,7 @@ CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnit( const char *ast_filename); /** - * \brief Create a translation unit from an AST file (\c -emit-ast). + * Create a translation unit from an AST file (\c -emit-ast). * * \param[out] out_TU A non-NULL pointer to store the created * \c CXTranslationUnit. @@ -1198,7 +1205,7 @@ CINDEX_LINKAGE enum CXErrorCode clang_createTranslationUnit2( CXTranslationUnit *out_TU); /** - * \brief Flags that control the creation of translation units. + * Flags that control the creation of translation units. * * The enumerators in this enumeration type are meant to be bitwise * ORed together to specify which options should be used when @@ -1206,13 +1213,13 @@ CINDEX_LINKAGE enum CXErrorCode clang_createTranslationUnit2( */ enum CXTranslationUnit_Flags { /** - * \brief Used to indicate that no special translation-unit options are + * Used to indicate that no special translation-unit options are * needed. */ CXTranslationUnit_None = 0x0, /** - * \brief Used to indicate that the parser should construct a "detailed" + * Used to indicate that the parser should construct a "detailed" * preprocessing record, including all macro definitions and instantiations. * * Constructing a detailed preprocessing record requires more memory @@ -1224,7 +1231,7 @@ enum CXTranslationUnit_Flags { CXTranslationUnit_DetailedPreprocessingRecord = 0x01, /** - * \brief Used to indicate that the translation unit is incomplete. + * Used to indicate that the translation unit is incomplete. * * When a translation unit is considered "incomplete", semantic * analysis that is typically performed at the end of the @@ -1237,7 +1244,7 @@ enum CXTranslationUnit_Flags { CXTranslationUnit_Incomplete = 0x02, /** - * \brief Used to indicate that the translation unit should be built with an + * Used to indicate that the translation unit should be built with an * implicit precompiled header for the preamble. * * An implicit precompiled header is used as an optimization when a @@ -1253,7 +1260,7 @@ enum CXTranslationUnit_Flags { CXTranslationUnit_PrecompiledPreamble = 0x04, /** - * \brief Used to indicate that the translation unit should cache some + * Used to indicate that the translation unit should cache some * code-completion results with each reparse of the source file. * * Caching of code-completion results is a performance optimization that @@ -1263,7 +1270,7 @@ enum CXTranslationUnit_Flags { CXTranslationUnit_CacheCompletionResults = 0x08, /** - * \brief Used to indicate that the translation unit will be serialized with + * Used to indicate that the translation unit will be serialized with * \c clang_saveTranslationUnit. * * This option is typically used when parsing a header with the intent of @@ -1272,7 +1279,7 @@ enum CXTranslationUnit_Flags { CXTranslationUnit_ForSerialization = 0x10, /** - * \brief DEPRECATED: Enabled chained precompiled preambles in C++. + * DEPRECATED: Enabled chained precompiled preambles in C++. * * Note: this is a *temporary* option that is available only while * we are testing C++ precompiled preamble support. It is deprecated. @@ -1280,7 +1287,7 @@ enum CXTranslationUnit_Flags { CXTranslationUnit_CXXChainedPCH = 0x20, /** - * \brief Used to indicate that function/method bodies should be skipped while + * Used to indicate that function/method bodies should be skipped while * parsing. * * This option can be used to search for declarations/definitions while @@ -1289,14 +1296,14 @@ enum CXTranslationUnit_Flags { CXTranslationUnit_SkipFunctionBodies = 0x40, /** - * \brief Used to indicate that brief documentation comments should be + * Used to indicate that brief documentation comments should be * included into the set of code completions returned from this translation * unit. */ CXTranslationUnit_IncludeBriefCommentsInCodeCompletion = 0x80, /** - * \brief Used to indicate that the precompiled preamble should be created on + * Used to indicate that the precompiled preamble should be created on * the first parse. Otherwise it will be created on the first reparse. This * trades runtime on the first parse (serializing the preamble takes time) for * reduced runtime on the second parse (can now reuse the preamble). @@ -1304,7 +1311,7 @@ enum CXTranslationUnit_Flags { CXTranslationUnit_CreatePreambleOnFirstParse = 0x100, /** - * \brief Do not stop processing when fatal errors are encountered. + * Do not stop processing when fatal errors are encountered. * * When fatal errors are encountered while parsing a translation unit, * semantic analysis is typically stopped early when compiling code. A common @@ -1315,13 +1322,21 @@ enum CXTranslationUnit_Flags { CXTranslationUnit_KeepGoing = 0x200, /** - * \brief Sets the preprocessor in a mode for parsing a single file only. + * Sets the preprocessor in a mode for parsing a single file only. + */ + CXTranslationUnit_SingleFileParse = 0x400, + + /** + * Used in combination with CXTranslationUnit_SkipFunctionBodies to + * constrain the skipping of function bodies to the preamble. + * + * The function bodies of the main file are not skipped. */ - CXTranslationUnit_SingleFileParse = 0x400 + CXTranslationUnit_LimitSkipFunctionBodiesToPreamble = 0x800 }; /** - * \brief Returns the set of flags that is suitable for parsing a translation + * Returns the set of flags that is suitable for parsing a translation * unit that is being edited. * * The set of flags returned provide options for \c clang_parseTranslationUnit() @@ -1335,7 +1350,7 @@ enum CXTranslationUnit_Flags { CINDEX_LINKAGE unsigned clang_defaultEditingTranslationUnitOptions(void); /** - * \brief Same as \c clang_parseTranslationUnit2, but returns + * Same as \c clang_parseTranslationUnit2, but returns * the \c CXTranslationUnit instead of an error code. In case of an error this * routine returns a \c NULL \c CXTranslationUnit, without further detailed * error codes. @@ -1350,7 +1365,7 @@ clang_parseTranslationUnit(CXIndex CIdx, unsigned options); /** - * \brief Parse the given source file and the translation unit corresponding + * Parse the given source file and the translation unit corresponding * to that file. * * This routine is the main entry point for the Clang C API, providing the @@ -1404,7 +1419,7 @@ clang_parseTranslationUnit2(CXIndex CIdx, CXTranslationUnit *out_TU); /** - * \brief Same as clang_parseTranslationUnit2 but requires a full command line + * Same as clang_parseTranslationUnit2 but requires a full command line * for \c command_line_args including argv[0]. This is useful if the standard * library paths are relative to the binary. */ @@ -1415,7 +1430,7 @@ CINDEX_LINKAGE enum CXErrorCode clang_parseTranslationUnit2FullArgv( unsigned options, CXTranslationUnit *out_TU); /** - * \brief Flags that control how translation units are saved. + * Flags that control how translation units are saved. * * The enumerators in this enumeration type are meant to be bitwise * ORed together to specify which options should be used when @@ -1423,13 +1438,13 @@ CINDEX_LINKAGE enum CXErrorCode clang_parseTranslationUnit2FullArgv( */ enum CXSaveTranslationUnit_Flags { /** - * \brief Used to indicate that no special saving options are needed. + * Used to indicate that no special saving options are needed. */ CXSaveTranslationUnit_None = 0x0 }; /** - * \brief Returns the set of flags that is suitable for saving a translation + * Returns the set of flags that is suitable for saving a translation * unit. * * The set of flags returned provide options for @@ -1440,17 +1455,17 @@ enum CXSaveTranslationUnit_Flags { CINDEX_LINKAGE unsigned clang_defaultSaveOptions(CXTranslationUnit TU); /** - * \brief Describes the kind of error that occurred (if any) in a call to + * Describes the kind of error that occurred (if any) in a call to * \c clang_saveTranslationUnit(). */ enum CXSaveError { /** - * \brief Indicates that no error occurred while saving a translation unit. + * Indicates that no error occurred while saving a translation unit. */ CXSaveError_None = 0, /** - * \brief Indicates that an unknown error occurred while attempting to save + * Indicates that an unknown error occurred while attempting to save * the file. * * This error typically indicates that file I/O failed when attempting to @@ -1459,7 +1474,7 @@ enum CXSaveError { CXSaveError_Unknown = 1, /** - * \brief Indicates that errors during translation prevented this attempt + * Indicates that errors during translation prevented this attempt * to save the translation unit. * * Errors that prevent the translation unit from being saved can be @@ -1468,14 +1483,14 @@ enum CXSaveError { CXSaveError_TranslationErrors = 2, /** - * \brief Indicates that the translation unit to be saved was somehow + * Indicates that the translation unit to be saved was somehow * invalid (e.g., NULL). */ CXSaveError_InvalidTU = 3 }; /** - * \brief Saves a translation unit into a serialized representation of + * Saves a translation unit into a serialized representation of * that translation unit on disk. * * Any translation unit that was parsed without error can be saved @@ -1502,7 +1517,7 @@ CINDEX_LINKAGE int clang_saveTranslationUnit(CXTranslationUnit TU, unsigned options); /** - * \brief Suspend a translation unit in order to free memory associated with it. + * Suspend a translation unit in order to free memory associated with it. * * A suspended translation unit uses significantly less memory but on the other * side does not support any other calls than \c clang_reparseTranslationUnit @@ -1511,12 +1526,12 @@ CINDEX_LINKAGE int clang_saveTranslationUnit(CXTranslationUnit TU, CINDEX_LINKAGE unsigned clang_suspendTranslationUnit(CXTranslationUnit); /** - * \brief Destroy the specified CXTranslationUnit object. + * Destroy the specified CXTranslationUnit object. */ CINDEX_LINKAGE void clang_disposeTranslationUnit(CXTranslationUnit); /** - * \brief Flags that control the reparsing of translation units. + * Flags that control the reparsing of translation units. * * The enumerators in this enumeration type are meant to be bitwise * ORed together to specify which options should be used when @@ -1524,13 +1539,13 @@ CINDEX_LINKAGE void clang_disposeTranslationUnit(CXTranslationUnit); */ enum CXReparse_Flags { /** - * \brief Used to indicate that no special reparsing options are needed. + * Used to indicate that no special reparsing options are needed. */ CXReparse_None = 0x0 }; /** - * \brief Returns the set of flags that is suitable for reparsing a translation + * Returns the set of flags that is suitable for reparsing a translation * unit. * * The set of flags returned provide options for @@ -1542,7 +1557,7 @@ enum CXReparse_Flags { CINDEX_LINKAGE unsigned clang_defaultReparseOptions(CXTranslationUnit TU); /** - * \brief Reparse the source files that produced this translation unit. + * Reparse the source files that produced this translation unit. * * This routine can be used to re-parse the source files that originally * created the given translation unit, for example because those source files @@ -1586,7 +1601,7 @@ CINDEX_LINKAGE int clang_reparseTranslationUnit(CXTranslationUnit TU, unsigned options); /** - * \brief Categorizes how memory is being used by a translation unit. + * Categorizes how memory is being used by a translation unit. */ enum CXTUResourceUsageKind { CXTUResourceUsage_AST = 1, @@ -1612,38 +1627,38 @@ enum CXTUResourceUsageKind { }; /** - * \brief Returns the human-readable null-terminated C string that represents + * Returns the human-readable null-terminated C string that represents * the name of the memory category. This string should never be freed. */ CINDEX_LINKAGE const char *clang_getTUResourceUsageName(enum CXTUResourceUsageKind kind); typedef struct CXTUResourceUsageEntry { - /* \brief The memory usage category. */ + /* The memory usage category. */ enum CXTUResourceUsageKind kind; - /* \brief Amount of resources used. + /* Amount of resources used. The units will depend on the resource kind. */ unsigned long amount; } CXTUResourceUsageEntry; /** - * \brief The memory usage of a CXTranslationUnit, broken into categories. + * The memory usage of a CXTranslationUnit, broken into categories. */ typedef struct CXTUResourceUsage { - /* \brief Private data member, used for queries. */ + /* Private data member, used for queries. */ void *data; - /* \brief The number of entries in the 'entries' array. */ + /* The number of entries in the 'entries' array. */ unsigned numEntries; - /* \brief An array of key-value pairs, representing the breakdown of memory + /* An array of key-value pairs, representing the breakdown of memory usage. */ CXTUResourceUsageEntry *entries; } CXTUResourceUsage; /** - * \brief Return the memory usage of a translation unit. This object + * Return the memory usage of a translation unit. This object * should be released with clang_disposeCXTUResourceUsage(). */ CINDEX_LINKAGE CXTUResourceUsage clang_getCXTUResourceUsage(CXTranslationUnit TU); @@ -1651,7 +1666,7 @@ CINDEX_LINKAGE CXTUResourceUsage clang_getCXTUResourceUsage(CXTranslationUnit TU CINDEX_LINKAGE void clang_disposeCXTUResourceUsage(CXTUResourceUsage usage); /** - * \brief Get target information for this translation unit. + * Get target information for this translation unit. * * The CXTargetInfo object cannot outlive the CXTranslationUnit object. */ @@ -1659,13 +1674,13 @@ CINDEX_LINKAGE CXTargetInfo clang_getTranslationUnitTargetInfo(CXTranslationUnit CTUnit); /** - * \brief Destroy the CXTargetInfo object. + * Destroy the CXTargetInfo object. */ CINDEX_LINKAGE void clang_TargetInfo_dispose(CXTargetInfo Info); /** - * \brief Get the normalized target triple as a string. + * Get the normalized target triple as a string. * * Returns the empty string in case of any error. */ @@ -1673,7 +1688,7 @@ CINDEX_LINKAGE CXString clang_TargetInfo_getTriple(CXTargetInfo Info); /** - * \brief Get the pointer width of the target in bits. + * Get the pointer width of the target in bits. * * Returns -1 in case of error. */ @@ -1685,12 +1700,12 @@ clang_TargetInfo_getPointerWidth(CXTargetInfo Info); */ /** - * \brief Describes the kind of entity that a cursor refers to. + * Describes the kind of entity that a cursor refers to. */ enum CXCursorKind { /* Declarations */ /** - * \brief A declaration whose specific kind is not exposed via this + * A declaration whose specific kind is not exposed via this * interface. * * Unexposed declarations have the same operations as any other kind @@ -1699,84 +1714,84 @@ enum CXCursorKind { * of the declaration is not reported. */ CXCursor_UnexposedDecl = 1, - /** \brief A C or C++ struct. */ + /** A C or C++ struct. */ CXCursor_StructDecl = 2, - /** \brief A C or C++ union. */ + /** A C or C++ union. */ CXCursor_UnionDecl = 3, - /** \brief A C++ class. */ + /** A C++ class. */ CXCursor_ClassDecl = 4, - /** \brief An enumeration. */ + /** An enumeration. */ CXCursor_EnumDecl = 5, /** - * \brief A field (in C) or non-static data member (in C++) in a + * A field (in C) or non-static data member (in C++) in a * struct, union, or C++ class. */ CXCursor_FieldDecl = 6, - /** \brief An enumerator constant. */ + /** An enumerator constant. */ CXCursor_EnumConstantDecl = 7, - /** \brief A function. */ + /** A function. */ CXCursor_FunctionDecl = 8, - /** \brief A variable. */ + /** A variable. */ CXCursor_VarDecl = 9, - /** \brief A function or method parameter. */ + /** A function or method parameter. */ CXCursor_ParmDecl = 10, - /** \brief An Objective-C \@interface. */ + /** An Objective-C \@interface. */ CXCursor_ObjCInterfaceDecl = 11, - /** \brief An Objective-C \@interface for a category. */ + /** An Objective-C \@interface for a category. */ CXCursor_ObjCCategoryDecl = 12, - /** \brief An Objective-C \@protocol declaration. */ + /** An Objective-C \@protocol declaration. */ CXCursor_ObjCProtocolDecl = 13, - /** \brief An Objective-C \@property declaration. */ + /** An Objective-C \@property declaration. */ CXCursor_ObjCPropertyDecl = 14, - /** \brief An Objective-C instance variable. */ + /** An Objective-C instance variable. */ CXCursor_ObjCIvarDecl = 15, - /** \brief An Objective-C instance method. */ + /** An Objective-C instance method. */ CXCursor_ObjCInstanceMethodDecl = 16, - /** \brief An Objective-C class method. */ + /** An Objective-C class method. */ CXCursor_ObjCClassMethodDecl = 17, - /** \brief An Objective-C \@implementation. */ + /** An Objective-C \@implementation. */ CXCursor_ObjCImplementationDecl = 18, - /** \brief An Objective-C \@implementation for a category. */ + /** An Objective-C \@implementation for a category. */ CXCursor_ObjCCategoryImplDecl = 19, - /** \brief A typedef. */ + /** A typedef. */ CXCursor_TypedefDecl = 20, - /** \brief A C++ class method. */ + /** A C++ class method. */ CXCursor_CXXMethod = 21, - /** \brief A C++ namespace. */ + /** A C++ namespace. */ CXCursor_Namespace = 22, - /** \brief A linkage specification, e.g. 'extern "C"'. */ + /** A linkage specification, e.g. 'extern "C"'. */ CXCursor_LinkageSpec = 23, - /** \brief A C++ constructor. */ + /** A C++ constructor. */ CXCursor_Constructor = 24, - /** \brief A C++ destructor. */ + /** A C++ destructor. */ CXCursor_Destructor = 25, - /** \brief A C++ conversion function. */ + /** A C++ conversion function. */ CXCursor_ConversionFunction = 26, - /** \brief A C++ template type parameter. */ + /** A C++ template type parameter. */ CXCursor_TemplateTypeParameter = 27, - /** \brief A C++ non-type template parameter. */ + /** A C++ non-type template parameter. */ CXCursor_NonTypeTemplateParameter = 28, - /** \brief A C++ template template parameter. */ + /** A C++ template template parameter. */ CXCursor_TemplateTemplateParameter = 29, - /** \brief A C++ function template. */ + /** A C++ function template. */ CXCursor_FunctionTemplate = 30, - /** \brief A C++ class template. */ + /** A C++ class template. */ CXCursor_ClassTemplate = 31, - /** \brief A C++ class template partial specialization. */ + /** A C++ class template partial specialization. */ CXCursor_ClassTemplatePartialSpecialization = 32, - /** \brief A C++ namespace alias declaration. */ + /** A C++ namespace alias declaration. */ CXCursor_NamespaceAlias = 33, - /** \brief A C++ using directive. */ + /** A C++ using directive. */ CXCursor_UsingDirective = 34, - /** \brief A C++ using declaration. */ + /** A C++ using declaration. */ CXCursor_UsingDeclaration = 35, - /** \brief A C++ alias declaration */ + /** A C++ alias declaration */ CXCursor_TypeAliasDecl = 36, - /** \brief An Objective-C \@synthesize definition. */ + /** An Objective-C \@synthesize definition. */ CXCursor_ObjCSynthesizeDecl = 37, - /** \brief An Objective-C \@dynamic definition. */ + /** An Objective-C \@dynamic definition. */ CXCursor_ObjCDynamicDecl = 38, - /** \brief An access specifier. */ + /** An access specifier. */ CXCursor_CXXAccessSpecifier = 39, CXCursor_FirstDecl = CXCursor_UnexposedDecl, @@ -1788,7 +1803,7 @@ enum CXCursorKind { CXCursor_ObjCProtocolRef = 41, CXCursor_ObjCClassRef = 42, /** - * \brief A reference to a type declaration. + * A reference to a type declaration. * * A type reference occurs anywhere where a type is named but not * declared. For example, given: @@ -1805,21 +1820,21 @@ enum CXCursorKind { CXCursor_TypeRef = 43, CXCursor_CXXBaseSpecifier = 44, /** - * \brief A reference to a class template, function template, template + * A reference to a class template, function template, template * template parameter, or class template partial specialization. */ CXCursor_TemplateRef = 45, /** - * \brief A reference to a namespace or namespace alias. + * A reference to a namespace or namespace alias. */ CXCursor_NamespaceRef = 46, /** - * \brief A reference to a member of a struct, union, or class that occurs in + * A reference to a member of a struct, union, or class that occurs in * some non-expression context, e.g., a designated initializer. */ CXCursor_MemberRef = 47, /** - * \brief A reference to a labeled statement. + * A reference to a labeled statement. * * This cursor kind is used to describe the jump to "start_over" in the * goto statement in the following example: @@ -1836,7 +1851,7 @@ enum CXCursorKind { CXCursor_LabelRef = 48, /** - * \brief A reference to a set of overloaded functions or function templates + * A reference to a set of overloaded functions or function templates * that has not yet been resolved to a specific function or function template. * * An overloaded declaration reference cursor occurs in C++ templates where @@ -1874,7 +1889,7 @@ enum CXCursorKind { CXCursor_OverloadedDeclRef = 49, /** - * \brief A reference to a variable that occurs in some non-expression + * A reference to a variable that occurs in some non-expression * context, e.g., a C++ lambda capture list. */ CXCursor_VariableRef = 50, @@ -1893,7 +1908,7 @@ enum CXCursorKind { CXCursor_FirstExpr = 100, /** - * \brief An expression whose specific kind is not exposed via this + * An expression whose specific kind is not exposed via this * interface. * * Unexposed expressions have the same operations as any other kind @@ -1904,103 +1919,103 @@ enum CXCursorKind { CXCursor_UnexposedExpr = 100, /** - * \brief An expression that refers to some value declaration, such + * An expression that refers to some value declaration, such * as a function, variable, or enumerator. */ CXCursor_DeclRefExpr = 101, /** - * \brief An expression that refers to a member of a struct, union, + * An expression that refers to a member of a struct, union, * class, Objective-C class, etc. */ CXCursor_MemberRefExpr = 102, - /** \brief An expression that calls a function. */ + /** An expression that calls a function. */ CXCursor_CallExpr = 103, - /** \brief An expression that sends a message to an Objective-C + /** An expression that sends a message to an Objective-C object or class. */ CXCursor_ObjCMessageExpr = 104, - /** \brief An expression that represents a block literal. */ + /** An expression that represents a block literal. */ CXCursor_BlockExpr = 105, - /** \brief An integer literal. + /** An integer literal. */ CXCursor_IntegerLiteral = 106, - /** \brief A floating point number literal. + /** A floating point number literal. */ CXCursor_FloatingLiteral = 107, - /** \brief An imaginary number literal. + /** An imaginary number literal. */ CXCursor_ImaginaryLiteral = 108, - /** \brief A string literal. + /** A string literal. */ CXCursor_StringLiteral = 109, - /** \brief A character literal. + /** A character literal. */ CXCursor_CharacterLiteral = 110, - /** \brief A parenthesized expression, e.g. "(1)". + /** A parenthesized expression, e.g. "(1)". * * This AST node is only formed if full location information is requested. */ CXCursor_ParenExpr = 111, - /** \brief This represents the unary-expression's (except sizeof and + /** This represents the unary-expression's (except sizeof and * alignof). */ CXCursor_UnaryOperator = 112, - /** \brief [C99 6.5.2.1] Array Subscripting. + /** [C99 6.5.2.1] Array Subscripting. */ CXCursor_ArraySubscriptExpr = 113, - /** \brief A builtin binary operation expression such as "x + y" or + /** A builtin binary operation expression such as "x + y" or * "x <= y". */ CXCursor_BinaryOperator = 114, - /** \brief Compound assignment such as "+=". + /** Compound assignment such as "+=". */ CXCursor_CompoundAssignOperator = 115, - /** \brief The ?: ternary operator. + /** The ?: ternary operator. */ CXCursor_ConditionalOperator = 116, - /** \brief An explicit cast in C (C99 6.5.4) or a C-style cast in C++ + /** An explicit cast in C (C99 6.5.4) or a C-style cast in C++ * (C++ [expr.cast]), which uses the syntax (Type)expr. * * For example: (int)f. */ CXCursor_CStyleCastExpr = 117, - /** \brief [C99 6.5.2.5] + /** [C99 6.5.2.5] */ CXCursor_CompoundLiteralExpr = 118, - /** \brief Describes an C or C++ initializer list. + /** Describes an C or C++ initializer list. */ CXCursor_InitListExpr = 119, - /** \brief The GNU address of label extension, representing &&label. + /** The GNU address of label extension, representing &&label. */ CXCursor_AddrLabelExpr = 120, - /** \brief This is the GNU Statement Expression extension: ({int X=4; X;}) + /** This is the GNU Statement Expression extension: ({int X=4; X;}) */ CXCursor_StmtExpr = 121, - /** \brief Represents a C11 generic selection. + /** Represents a C11 generic selection. */ CXCursor_GenericSelectionExpr = 122, - /** \brief Implements the GNU __null extension, which is a name for a null + /** Implements the GNU __null extension, which is a name for a null * pointer constant that has integral type (e.g., int or long) and is the same * size and alignment as a pointer. * @@ -2010,23 +2025,23 @@ enum CXCursorKind { */ CXCursor_GNUNullExpr = 123, - /** \brief C++'s static_cast<> expression. + /** C++'s static_cast<> expression. */ CXCursor_CXXStaticCastExpr = 124, - /** \brief C++'s dynamic_cast<> expression. + /** C++'s dynamic_cast<> expression. */ CXCursor_CXXDynamicCastExpr = 125, - /** \brief C++'s reinterpret_cast<> expression. + /** C++'s reinterpret_cast<> expression. */ CXCursor_CXXReinterpretCastExpr = 126, - /** \brief C++'s const_cast<> expression. + /** C++'s const_cast<> expression. */ CXCursor_CXXConstCastExpr = 127, - /** \brief Represents an explicit C++ type conversion that uses "functional" + /** Represents an explicit C++ type conversion that uses "functional" * notion (C++ [expr.type.conv]). * * Example: @@ -2036,60 +2051,60 @@ enum CXCursorKind { */ CXCursor_CXXFunctionalCastExpr = 128, - /** \brief A C++ typeid expression (C++ [expr.typeid]). + /** A C++ typeid expression (C++ [expr.typeid]). */ CXCursor_CXXTypeidExpr = 129, - /** \brief [C++ 2.13.5] C++ Boolean Literal. + /** [C++ 2.13.5] C++ Boolean Literal. */ CXCursor_CXXBoolLiteralExpr = 130, - /** \brief [C++0x 2.14.7] C++ Pointer Literal. + /** [C++0x 2.14.7] C++ Pointer Literal. */ CXCursor_CXXNullPtrLiteralExpr = 131, - /** \brief Represents the "this" expression in C++ + /** Represents the "this" expression in C++ */ CXCursor_CXXThisExpr = 132, - /** \brief [C++ 15] C++ Throw Expression. + /** [C++ 15] C++ Throw Expression. * * This handles 'throw' and 'throw' assignment-expression. When * assignment-expression isn't present, Op will be null. */ CXCursor_CXXThrowExpr = 133, - /** \brief A new expression for memory allocation and constructor calls, e.g: + /** A new expression for memory allocation and constructor calls, e.g: * "new CXXNewExpr(foo)". */ CXCursor_CXXNewExpr = 134, - /** \brief A delete expression for memory deallocation and destructor calls, + /** A delete expression for memory deallocation and destructor calls, * e.g. "delete[] pArray". */ CXCursor_CXXDeleteExpr = 135, - /** \brief A unary expression. (noexcept, sizeof, or other traits) + /** A unary expression. (noexcept, sizeof, or other traits) */ CXCursor_UnaryExpr = 136, - /** \brief An Objective-C string literal i.e. @"foo". + /** An Objective-C string literal i.e. @"foo". */ CXCursor_ObjCStringLiteral = 137, - /** \brief An Objective-C \@encode expression. + /** An Objective-C \@encode expression. */ CXCursor_ObjCEncodeExpr = 138, - /** \brief An Objective-C \@selector expression. + /** An Objective-C \@selector expression. */ CXCursor_ObjCSelectorExpr = 139, - /** \brief An Objective-C \@protocol expression. + /** An Objective-C \@protocol expression. */ CXCursor_ObjCProtocolExpr = 140, - /** \brief An Objective-C "bridged" cast expression, which casts between + /** An Objective-C "bridged" cast expression, which casts between * Objective-C pointers and C pointers, transferring ownership in the process. * * \code @@ -2098,7 +2113,7 @@ enum CXCursorKind { */ CXCursor_ObjCBridgedCastExpr = 141, - /** \brief Represents a C++0x pack expansion that produces a sequence of + /** Represents a C++0x pack expansion that produces a sequence of * expressions. * * A pack expansion expression contains a pattern (which itself is an @@ -2113,7 +2128,7 @@ enum CXCursorKind { */ CXCursor_PackExpansionExpr = 142, - /** \brief Represents an expression that computes the length of a parameter + /** Represents an expression that computes the length of a parameter * pack. * * \code @@ -2125,7 +2140,7 @@ enum CXCursorKind { */ CXCursor_SizeOfPackExpr = 143, - /* \brief Represents a C++ lambda expression that produces a local function + /* Represents a C++ lambda expression that produces a local function * object. * * \code @@ -2139,28 +2154,33 @@ enum CXCursorKind { */ CXCursor_LambdaExpr = 144, - /** \brief Objective-c Boolean Literal. + /** Objective-c Boolean Literal. */ CXCursor_ObjCBoolLiteralExpr = 145, - /** \brief Represents the "self" expression in an Objective-C method. + /** Represents the "self" expression in an Objective-C method. */ CXCursor_ObjCSelfExpr = 146, - /** \brief OpenMP 4.0 [2.4, Array Section]. + /** OpenMP 4.0 [2.4, Array Section]. */ CXCursor_OMPArraySectionExpr = 147, - /** \brief Represents an @available(...) check. + /** Represents an @available(...) check. */ CXCursor_ObjCAvailabilityCheckExpr = 148, - CXCursor_LastExpr = CXCursor_ObjCAvailabilityCheckExpr, + /** + * Fixed point literal + */ + CXCursor_FixedPointLiteral = 149, + + CXCursor_LastExpr = CXCursor_FixedPointLiteral, /* Statements */ CXCursor_FirstStmt = 200, /** - * \brief A statement whose specific kind is not exposed via this + * A statement whose specific kind is not exposed via this * interface. * * Unexposed statements have the same operations as any other kind of @@ -2170,7 +2190,7 @@ enum CXCursorKind { */ CXCursor_UnexposedStmt = 200, - /** \brief A labelled statement in a function. + /** A labelled statement in a function. * * This cursor kind is used to describe the "start_over:" label statement in * the following example: @@ -2183,329 +2203,329 @@ enum CXCursorKind { */ CXCursor_LabelStmt = 201, - /** \brief A group of statements like { stmt stmt }. + /** A group of statements like { stmt stmt }. * * This cursor kind is used to describe compound statements, e.g. function * bodies. */ CXCursor_CompoundStmt = 202, - /** \brief A case statement. + /** A case statement. */ CXCursor_CaseStmt = 203, - /** \brief A default statement. + /** A default statement. */ CXCursor_DefaultStmt = 204, - /** \brief An if statement + /** An if statement */ CXCursor_IfStmt = 205, - /** \brief A switch statement. + /** A switch statement. */ CXCursor_SwitchStmt = 206, - /** \brief A while statement. + /** A while statement. */ CXCursor_WhileStmt = 207, - /** \brief A do statement. + /** A do statement. */ CXCursor_DoStmt = 208, - /** \brief A for statement. + /** A for statement. */ CXCursor_ForStmt = 209, - /** \brief A goto statement. + /** A goto statement. */ CXCursor_GotoStmt = 210, - /** \brief An indirect goto statement. + /** An indirect goto statement. */ CXCursor_IndirectGotoStmt = 211, - /** \brief A continue statement. + /** A continue statement. */ CXCursor_ContinueStmt = 212, - /** \brief A break statement. + /** A break statement. */ CXCursor_BreakStmt = 213, - /** \brief A return statement. + /** A return statement. */ CXCursor_ReturnStmt = 214, - /** \brief A GCC inline assembly statement extension. + /** A GCC inline assembly statement extension. */ CXCursor_GCCAsmStmt = 215, CXCursor_AsmStmt = CXCursor_GCCAsmStmt, - /** \brief Objective-C's overall \@try-\@catch-\@finally statement. + /** Objective-C's overall \@try-\@catch-\@finally statement. */ CXCursor_ObjCAtTryStmt = 216, - /** \brief Objective-C's \@catch statement. + /** Objective-C's \@catch statement. */ CXCursor_ObjCAtCatchStmt = 217, - /** \brief Objective-C's \@finally statement. + /** Objective-C's \@finally statement. */ CXCursor_ObjCAtFinallyStmt = 218, - /** \brief Objective-C's \@throw statement. + /** Objective-C's \@throw statement. */ CXCursor_ObjCAtThrowStmt = 219, - /** \brief Objective-C's \@synchronized statement. + /** Objective-C's \@synchronized statement. */ CXCursor_ObjCAtSynchronizedStmt = 220, - /** \brief Objective-C's autorelease pool statement. + /** Objective-C's autorelease pool statement. */ CXCursor_ObjCAutoreleasePoolStmt = 221, - /** \brief Objective-C's collection statement. + /** Objective-C's collection statement. */ CXCursor_ObjCForCollectionStmt = 222, - /** \brief C++'s catch statement. + /** C++'s catch statement. */ CXCursor_CXXCatchStmt = 223, - /** \brief C++'s try statement. + /** C++'s try statement. */ CXCursor_CXXTryStmt = 224, - /** \brief C++'s for (* : *) statement. + /** C++'s for (* : *) statement. */ CXCursor_CXXForRangeStmt = 225, - /** \brief Windows Structured Exception Handling's try statement. + /** Windows Structured Exception Handling's try statement. */ CXCursor_SEHTryStmt = 226, - /** \brief Windows Structured Exception Handling's except statement. + /** Windows Structured Exception Handling's except statement. */ CXCursor_SEHExceptStmt = 227, - /** \brief Windows Structured Exception Handling's finally statement. + /** Windows Structured Exception Handling's finally statement. */ CXCursor_SEHFinallyStmt = 228, - /** \brief A MS inline assembly statement extension. + /** A MS inline assembly statement extension. */ CXCursor_MSAsmStmt = 229, - /** \brief The null statement ";": C99 6.8.3p3. + /** The null statement ";": C99 6.8.3p3. * * This cursor kind is used to describe the null statement. */ CXCursor_NullStmt = 230, - /** \brief Adaptor class for mixing declarations with statements and + /** Adaptor class for mixing declarations with statements and * expressions. */ CXCursor_DeclStmt = 231, - /** \brief OpenMP parallel directive. + /** OpenMP parallel directive. */ CXCursor_OMPParallelDirective = 232, - /** \brief OpenMP SIMD directive. + /** OpenMP SIMD directive. */ CXCursor_OMPSimdDirective = 233, - /** \brief OpenMP for directive. + /** OpenMP for directive. */ CXCursor_OMPForDirective = 234, - /** \brief OpenMP sections directive. + /** OpenMP sections directive. */ CXCursor_OMPSectionsDirective = 235, - /** \brief OpenMP section directive. + /** OpenMP section directive. */ CXCursor_OMPSectionDirective = 236, - /** \brief OpenMP single directive. + /** OpenMP single directive. */ CXCursor_OMPSingleDirective = 237, - /** \brief OpenMP parallel for directive. + /** OpenMP parallel for directive. */ CXCursor_OMPParallelForDirective = 238, - /** \brief OpenMP parallel sections directive. + /** OpenMP parallel sections directive. */ CXCursor_OMPParallelSectionsDirective = 239, - /** \brief OpenMP task directive. + /** OpenMP task directive. */ CXCursor_OMPTaskDirective = 240, - /** \brief OpenMP master directive. + /** OpenMP master directive. */ CXCursor_OMPMasterDirective = 241, - /** \brief OpenMP critical directive. + /** OpenMP critical directive. */ CXCursor_OMPCriticalDirective = 242, - /** \brief OpenMP taskyield directive. + /** OpenMP taskyield directive. */ CXCursor_OMPTaskyieldDirective = 243, - /** \brief OpenMP barrier directive. + /** OpenMP barrier directive. */ CXCursor_OMPBarrierDirective = 244, - /** \brief OpenMP taskwait directive. + /** OpenMP taskwait directive. */ CXCursor_OMPTaskwaitDirective = 245, - /** \brief OpenMP flush directive. + /** OpenMP flush directive. */ CXCursor_OMPFlushDirective = 246, - /** \brief Windows Structured Exception Handling's leave statement. + /** Windows Structured Exception Handling's leave statement. */ CXCursor_SEHLeaveStmt = 247, - /** \brief OpenMP ordered directive. + /** OpenMP ordered directive. */ CXCursor_OMPOrderedDirective = 248, - /** \brief OpenMP atomic directive. + /** OpenMP atomic directive. */ CXCursor_OMPAtomicDirective = 249, - /** \brief OpenMP for SIMD directive. + /** OpenMP for SIMD directive. */ CXCursor_OMPForSimdDirective = 250, - /** \brief OpenMP parallel for SIMD directive. + /** OpenMP parallel for SIMD directive. */ CXCursor_OMPParallelForSimdDirective = 251, - /** \brief OpenMP target directive. + /** OpenMP target directive. */ CXCursor_OMPTargetDirective = 252, - /** \brief OpenMP teams directive. + /** OpenMP teams directive. */ CXCursor_OMPTeamsDirective = 253, - /** \brief OpenMP taskgroup directive. + /** OpenMP taskgroup directive. */ CXCursor_OMPTaskgroupDirective = 254, - /** \brief OpenMP cancellation point directive. + /** OpenMP cancellation point directive. */ CXCursor_OMPCancellationPointDirective = 255, - /** \brief OpenMP cancel directive. + /** OpenMP cancel directive. */ CXCursor_OMPCancelDirective = 256, - /** \brief OpenMP target data directive. + /** OpenMP target data directive. */ CXCursor_OMPTargetDataDirective = 257, - /** \brief OpenMP taskloop directive. + /** OpenMP taskloop directive. */ CXCursor_OMPTaskLoopDirective = 258, - /** \brief OpenMP taskloop simd directive. + /** OpenMP taskloop simd directive. */ CXCursor_OMPTaskLoopSimdDirective = 259, - /** \brief OpenMP distribute directive. + /** OpenMP distribute directive. */ CXCursor_OMPDistributeDirective = 260, - /** \brief OpenMP target enter data directive. + /** OpenMP target enter data directive. */ CXCursor_OMPTargetEnterDataDirective = 261, - /** \brief OpenMP target exit data directive. + /** OpenMP target exit data directive. */ CXCursor_OMPTargetExitDataDirective = 262, - /** \brief OpenMP target parallel directive. + /** OpenMP target parallel directive. */ CXCursor_OMPTargetParallelDirective = 263, - /** \brief OpenMP target parallel for directive. + /** OpenMP target parallel for directive. */ CXCursor_OMPTargetParallelForDirective = 264, - /** \brief OpenMP target update directive. + /** OpenMP target update directive. */ CXCursor_OMPTargetUpdateDirective = 265, - /** \brief OpenMP distribute parallel for directive. + /** OpenMP distribute parallel for directive. */ CXCursor_OMPDistributeParallelForDirective = 266, - /** \brief OpenMP distribute parallel for simd directive. + /** OpenMP distribute parallel for simd directive. */ CXCursor_OMPDistributeParallelForSimdDirective = 267, - /** \brief OpenMP distribute simd directive. + /** OpenMP distribute simd directive. */ CXCursor_OMPDistributeSimdDirective = 268, - /** \brief OpenMP target parallel for simd directive. + /** OpenMP target parallel for simd directive. */ CXCursor_OMPTargetParallelForSimdDirective = 269, - /** \brief OpenMP target simd directive. + /** OpenMP target simd directive. */ CXCursor_OMPTargetSimdDirective = 270, - /** \brief OpenMP teams distribute directive. + /** OpenMP teams distribute directive. */ CXCursor_OMPTeamsDistributeDirective = 271, - /** \brief OpenMP teams distribute simd directive. + /** OpenMP teams distribute simd directive. */ CXCursor_OMPTeamsDistributeSimdDirective = 272, - /** \brief OpenMP teams distribute parallel for simd directive. + /** OpenMP teams distribute parallel for simd directive. */ CXCursor_OMPTeamsDistributeParallelForSimdDirective = 273, - /** \brief OpenMP teams distribute parallel for directive. + /** OpenMP teams distribute parallel for directive. */ CXCursor_OMPTeamsDistributeParallelForDirective = 274, - /** \brief OpenMP target teams directive. + /** OpenMP target teams directive. */ CXCursor_OMPTargetTeamsDirective = 275, - /** \brief OpenMP target teams distribute directive. + /** OpenMP target teams distribute directive. */ CXCursor_OMPTargetTeamsDistributeDirective = 276, - /** \brief OpenMP target teams distribute parallel for directive. + /** OpenMP target teams distribute parallel for directive. */ CXCursor_OMPTargetTeamsDistributeParallelForDirective = 277, - /** \brief OpenMP target teams distribute parallel for simd directive. + /** OpenMP target teams distribute parallel for simd directive. */ CXCursor_OMPTargetTeamsDistributeParallelForSimdDirective = 278, - /** \brief OpenMP target teams distribute simd directive. + /** OpenMP target teams distribute simd directive. */ CXCursor_OMPTargetTeamsDistributeSimdDirective = 279, CXCursor_LastStmt = CXCursor_OMPTargetTeamsDistributeSimdDirective, /** - * \brief Cursor that represents the translation unit itself. + * Cursor that represents the translation unit itself. * * The translation unit cursor exists primarily to act as the root * cursor for traversing the contents of a translation unit. @@ -2515,7 +2535,7 @@ enum CXCursorKind { /* Attributes */ CXCursor_FirstAttr = 400, /** - * \brief An attribute whose specific kind is not exposed via this + * An attribute whose specific kind is not exposed via this * interface. */ CXCursor_UnexposedAttr = 400, @@ -2552,29 +2572,29 @@ enum CXCursorKind { /* Extra Declarations */ /** - * \brief A module import declaration. + * A module import declaration. */ CXCursor_ModuleImportDecl = 600, CXCursor_TypeAliasTemplateDecl = 601, /** - * \brief A static_assert or _Static_assert node + * A static_assert or _Static_assert node */ CXCursor_StaticAssert = 602, /** - * \brief a friend declaration. + * a friend declaration. */ CXCursor_FriendDecl = 603, CXCursor_FirstExtraDecl = CXCursor_ModuleImportDecl, CXCursor_LastExtraDecl = CXCursor_FriendDecl, /** - * \brief A code completion overload candidate. + * A code completion overload candidate. */ CXCursor_OverloadCandidate = 700 }; /** - * \brief A cursor representing some element in the abstract syntax tree for + * A cursor representing some element in the abstract syntax tree for * a translation unit. * * The cursor abstraction unifies the different kinds of entities in a @@ -2604,12 +2624,12 @@ typedef struct { */ /** - * \brief Retrieve the NULL cursor, which represents no entity. + * Retrieve the NULL cursor, which represents no entity. */ CINDEX_LINKAGE CXCursor clang_getNullCursor(void); /** - * \brief Retrieve the cursor that represents the given translation unit. + * Retrieve the cursor that represents the given translation unit. * * The translation unit cursor can be used to start traversing the * various declarations within the given translation unit. @@ -2617,32 +2637,42 @@ CINDEX_LINKAGE CXCursor clang_getNullCursor(void); CINDEX_LINKAGE CXCursor clang_getTranslationUnitCursor(CXTranslationUnit); /** - * \brief Determine whether two cursors are equivalent. + * Determine whether two cursors are equivalent. */ CINDEX_LINKAGE unsigned clang_equalCursors(CXCursor, CXCursor); /** - * \brief Returns non-zero if \p cursor is null. + * Returns non-zero if \p cursor is null. */ CINDEX_LINKAGE int clang_Cursor_isNull(CXCursor cursor); /** - * \brief Compute a hash value for the given cursor. + * Compute a hash value for the given cursor. */ CINDEX_LINKAGE unsigned clang_hashCursor(CXCursor); /** - * \brief Retrieve the kind of the given cursor. + * Retrieve the kind of the given cursor. */ CINDEX_LINKAGE enum CXCursorKind clang_getCursorKind(CXCursor); /** - * \brief Determine whether the given cursor kind represents a declaration. + * Determine whether the given cursor kind represents a declaration. */ CINDEX_LINKAGE unsigned clang_isDeclaration(enum CXCursorKind); /** - * \brief Determine whether the given cursor kind represents a simple + * Determine whether the given declaration is invalid. + * + * A declaration is invalid if it could not be parsed successfully. + * + * \returns non-zero if the cursor represents a declaration and it is + * invalid, otherwise NULL. + */ +CINDEX_LINKAGE unsigned clang_isInvalidDeclaration(CXCursor); + +/** + * Determine whether the given cursor kind represents a simple * reference. * * Note that other kinds of cursors (such as expressions) can also refer to @@ -2652,90 +2682,90 @@ CINDEX_LINKAGE unsigned clang_isDeclaration(enum CXCursorKind); CINDEX_LINKAGE unsigned clang_isReference(enum CXCursorKind); /** - * \brief Determine whether the given cursor kind represents an expression. + * Determine whether the given cursor kind represents an expression. */ CINDEX_LINKAGE unsigned clang_isExpression(enum CXCursorKind); /** - * \brief Determine whether the given cursor kind represents a statement. + * Determine whether the given cursor kind represents a statement. */ CINDEX_LINKAGE unsigned clang_isStatement(enum CXCursorKind); /** - * \brief Determine whether the given cursor kind represents an attribute. + * Determine whether the given cursor kind represents an attribute. */ CINDEX_LINKAGE unsigned clang_isAttribute(enum CXCursorKind); /** - * \brief Determine whether the given cursor has any attributes. + * Determine whether the given cursor has any attributes. */ CINDEX_LINKAGE unsigned clang_Cursor_hasAttrs(CXCursor C); /** - * \brief Determine whether the given cursor kind represents an invalid + * Determine whether the given cursor kind represents an invalid * cursor. */ CINDEX_LINKAGE unsigned clang_isInvalid(enum CXCursorKind); /** - * \brief Determine whether the given cursor kind represents a translation + * Determine whether the given cursor kind represents a translation * unit. */ CINDEX_LINKAGE unsigned clang_isTranslationUnit(enum CXCursorKind); /*** - * \brief Determine whether the given cursor represents a preprocessing + * Determine whether the given cursor represents a preprocessing * element, such as a preprocessor directive or macro instantiation. */ CINDEX_LINKAGE unsigned clang_isPreprocessing(enum CXCursorKind); /*** - * \brief Determine whether the given cursor represents a currently + * Determine whether the given cursor represents a currently * unexposed piece of the AST (e.g., CXCursor_UnexposedStmt). */ CINDEX_LINKAGE unsigned clang_isUnexposed(enum CXCursorKind); /** - * \brief Describe the linkage of the entity referred to by a cursor. + * Describe the linkage of the entity referred to by a cursor. */ enum CXLinkageKind { - /** \brief This value indicates that no linkage information is available + /** This value indicates that no linkage information is available * for a provided CXCursor. */ CXLinkage_Invalid, /** - * \brief This is the linkage for variables, parameters, and so on that + * This is the linkage for variables, parameters, and so on that * have automatic storage. This covers normal (non-extern) local variables. */ CXLinkage_NoLinkage, - /** \brief This is the linkage for static variables and static functions. */ + /** This is the linkage for static variables and static functions. */ CXLinkage_Internal, - /** \brief This is the linkage for entities with external linkage that live + /** This is the linkage for entities with external linkage that live * in C++ anonymous namespaces.*/ CXLinkage_UniqueExternal, - /** \brief This is the linkage for entities with true, external linkage. */ + /** This is the linkage for entities with true, external linkage. */ CXLinkage_External }; /** - * \brief Determine the linkage of the entity referred to by a given cursor. + * Determine the linkage of the entity referred to by a given cursor. */ CINDEX_LINKAGE enum CXLinkageKind clang_getCursorLinkage(CXCursor cursor); enum CXVisibilityKind { - /** \brief This value indicates that no visibility information is available + /** This value indicates that no visibility information is available * for a provided CXCursor. */ CXVisibility_Invalid, - /** \brief Symbol not seen by the linker. */ + /** Symbol not seen by the linker. */ CXVisibility_Hidden, - /** \brief Symbol seen by the linker but resolves to a symbol inside this object. */ + /** Symbol seen by the linker but resolves to a symbol inside this object. */ CXVisibility_Protected, - /** \brief Symbol seen by the linker and acts like a normal symbol. */ + /** Symbol seen by the linker and acts like a normal symbol. */ CXVisibility_Default }; /** - * \brief Describe the visibility of the entity referred to by a cursor. + * Describe the visibility of the entity referred to by a cursor. * * This returns the default visibility if not explicitly specified by * a visibility attribute. The default visibility may be changed by @@ -2748,7 +2778,7 @@ enum CXVisibilityKind { CINDEX_LINKAGE enum CXVisibilityKind clang_getCursorVisibility(CXCursor cursor); /** - * \brief Determine the availability of the entity that this cursor refers to, + * Determine the availability of the entity that this cursor refers to, * taking the current target platform into account. * * \param cursor The cursor to query. @@ -2764,39 +2794,39 @@ clang_getCursorAvailability(CXCursor cursor); */ typedef struct CXPlatformAvailability { /** - * \brief A string that describes the platform for which this structure + * A string that describes the platform for which this structure * provides availability information. * * Possible values are "ios" or "macos". */ CXString Platform; /** - * \brief The version number in which this entity was introduced. + * The version number in which this entity was introduced. */ CXVersion Introduced; /** - * \brief The version number in which this entity was deprecated (but is + * The version number in which this entity was deprecated (but is * still available). */ CXVersion Deprecated; /** - * \brief The version number in which this entity was obsoleted, and therefore + * The version number in which this entity was obsoleted, and therefore * is no longer available. */ CXVersion Obsoleted; /** - * \brief Whether the entity is unconditionally unavailable on this platform. + * Whether the entity is unconditionally unavailable on this platform. */ int Unavailable; /** - * \brief An optional message to provide to a user of this API, e.g., to + * An optional message to provide to a user of this API, e.g., to * suggest replacement APIs. */ CXString Message; } CXPlatformAvailability; /** - * \brief Determine the availability of the entity that this cursor refers to + * Determine the availability of the entity that this cursor refers to * on any platforms for which availability information is known. * * \param cursor The cursor to query. @@ -2841,13 +2871,13 @@ clang_getCursorPlatformAvailability(CXCursor cursor, int availability_size); /** - * \brief Free the memory associated with a \c CXPlatformAvailability structure. + * Free the memory associated with a \c CXPlatformAvailability structure. */ CINDEX_LINKAGE void clang_disposeCXPlatformAvailability(CXPlatformAvailability *availability); /** - * \brief Describe the "language" of the entity referred to by a cursor. + * Describe the "language" of the entity referred to by a cursor. */ enum CXLanguageKind { CXLanguage_Invalid = 0, @@ -2857,12 +2887,12 @@ enum CXLanguageKind { }; /** - * \brief Determine the "language" of the entity referred to by a given cursor. + * Determine the "language" of the entity referred to by a given cursor. */ CINDEX_LINKAGE enum CXLanguageKind clang_getCursorLanguage(CXCursor cursor); /** - * \brief Describe the "thread-local storage (TLS) kind" of the declaration + * Describe the "thread-local storage (TLS) kind" of the declaration * referred to by a cursor. */ enum CXTLSKind { @@ -2872,33 +2902,33 @@ enum CXTLSKind { }; /** - * \brief Determine the "thread-local storage (TLS) kind" of the declaration + * Determine the "thread-local storage (TLS) kind" of the declaration * referred to by a cursor. */ CINDEX_LINKAGE enum CXTLSKind clang_getCursorTLSKind(CXCursor cursor); /** - * \brief Returns the translation unit that a cursor originated from. + * Returns the translation unit that a cursor originated from. */ CINDEX_LINKAGE CXTranslationUnit clang_Cursor_getTranslationUnit(CXCursor); /** - * \brief A fast container representing a set of CXCursors. + * A fast container representing a set of CXCursors. */ typedef struct CXCursorSetImpl *CXCursorSet; /** - * \brief Creates an empty CXCursorSet. + * Creates an empty CXCursorSet. */ CINDEX_LINKAGE CXCursorSet clang_createCXCursorSet(void); /** - * \brief Disposes a CXCursorSet and releases its associated memory. + * Disposes a CXCursorSet and releases its associated memory. */ CINDEX_LINKAGE void clang_disposeCXCursorSet(CXCursorSet cset); /** - * \brief Queries a CXCursorSet to see if it contains a specific CXCursor. + * Queries a CXCursorSet to see if it contains a specific CXCursor. * * \returns non-zero if the set contains the specified cursor. */ @@ -2906,7 +2936,7 @@ CINDEX_LINKAGE unsigned clang_CXCursorSet_contains(CXCursorSet cset, CXCursor cursor); /** - * \brief Inserts a CXCursor into a CXCursorSet. + * Inserts a CXCursor into a CXCursorSet. * * \returns zero if the CXCursor was already in the set, and non-zero otherwise. */ @@ -2914,7 +2944,7 @@ CINDEX_LINKAGE unsigned clang_CXCursorSet_insert(CXCursorSet cset, CXCursor cursor); /** - * \brief Determine the semantic parent of the given cursor. + * Determine the semantic parent of the given cursor. * * The semantic parent of a cursor is the cursor that semantically contains * the given \p cursor. For many declarations, the lexical and semantic parents @@ -2949,7 +2979,7 @@ CINDEX_LINKAGE unsigned clang_CXCursorSet_insert(CXCursorSet cset, CINDEX_LINKAGE CXCursor clang_getCursorSemanticParent(CXCursor cursor); /** - * \brief Determine the lexical parent of the given cursor. + * Determine the lexical parent of the given cursor. * * The lexical parent of a cursor is the cursor in which the given \p cursor * was actually written. For many declarations, the lexical and semantic parents @@ -2985,7 +3015,7 @@ CINDEX_LINKAGE CXCursor clang_getCursorSemanticParent(CXCursor cursor); CINDEX_LINKAGE CXCursor clang_getCursorLexicalParent(CXCursor cursor); /** - * \brief Determine the set of methods that are overridden by the given + * Determine the set of methods that are overridden by the given * method. * * In both Objective-C and C++, a method (aka virtual member function, @@ -3032,13 +3062,13 @@ CINDEX_LINKAGE void clang_getOverriddenCursors(CXCursor cursor, unsigned *num_overridden); /** - * \brief Free the set of overridden cursors returned by \c + * Free the set of overridden cursors returned by \c * clang_getOverriddenCursors(). */ CINDEX_LINKAGE void clang_disposeOverriddenCursors(CXCursor *overridden); /** - * \brief Retrieve the file that is included by the given inclusion directive + * Retrieve the file that is included by the given inclusion directive * cursor. */ CINDEX_LINKAGE CXFile clang_getIncludedFile(CXCursor cursor); @@ -3059,7 +3089,7 @@ CINDEX_LINKAGE CXFile clang_getIncludedFile(CXCursor cursor); */ /** - * \brief Map a source location to the cursor that describes the entity at that + * Map a source location to the cursor that describes the entity at that * location in the source code. * * clang_getCursor() maps an arbitrary source location within a translation @@ -3076,7 +3106,7 @@ CINDEX_LINKAGE CXFile clang_getIncludedFile(CXCursor cursor); CINDEX_LINKAGE CXCursor clang_getCursor(CXTranslationUnit, CXSourceLocation); /** - * \brief Retrieve the physical location of the source constructor referenced + * Retrieve the physical location of the source constructor referenced * by the given cursor. * * The location of a declaration is typically the location of the name of that @@ -3088,7 +3118,7 @@ CINDEX_LINKAGE CXCursor clang_getCursor(CXTranslationUnit, CXSourceLocation); CINDEX_LINKAGE CXSourceLocation clang_getCursorLocation(CXCursor); /** - * \brief Retrieve the physical extent of the source construct referenced by + * Retrieve the physical extent of the source construct referenced by * the given cursor. * * The extent of a cursor starts with the file/line/column pointing at the @@ -3111,16 +3141,16 @@ CINDEX_LINKAGE CXSourceRange clang_getCursorExtent(CXCursor); */ /** - * \brief Describes the kind of type + * Describes the kind of type */ enum CXTypeKind { /** - * \brief Represents an invalid type (e.g., where no type is available). + * Represents an invalid type (e.g., where no type is available). */ CXType_Invalid = 0, /** - * \brief A type whose specific kind is not exposed via this + * A type whose specific kind is not exposed via this * interface. */ CXType_Unexposed = 1, @@ -3157,8 +3187,14 @@ enum CXTypeKind { CXType_Float128 = 30, CXType_Half = 31, CXType_Float16 = 32, + CXType_ShortAccum = 33, + CXType_Accum = 34, + CXType_LongAccum = 35, + CXType_UShortAccum = 36, + CXType_UAccum = 37, + CXType_ULongAccum = 38, CXType_FirstBuiltin = CXType_Void, - CXType_LastBuiltin = CXType_Float16, + CXType_LastBuiltin = CXType_ULongAccum, CXType_Complex = 100, CXType_Pointer = 101, @@ -3181,7 +3217,7 @@ enum CXTypeKind { CXType_Auto = 118, /** - * \brief Represents a type that was referred to using an elaborated type keyword. + * Represents a type that was referred to using an elaborated type keyword. * * E.g., struct S, or via a qualified name, e.g., N::M::type, or both. */ @@ -3234,7 +3270,7 @@ enum CXTypeKind { }; /** - * \brief Describes the calling convention of a function type + * Describes the calling convention of a function type */ enum CXCallingConv { CXCallingConv_Default = 0, @@ -3261,7 +3297,7 @@ enum CXCallingConv { }; /** - * \brief The type of an element in the abstract syntax tree. + * The type of an element in the abstract syntax tree. * */ typedef struct { @@ -3270,12 +3306,12 @@ typedef struct { } CXType; /** - * \brief Retrieve the type of a CXCursor (if any). + * Retrieve the type of a CXCursor (if any). */ CINDEX_LINKAGE CXType clang_getCursorType(CXCursor C); /** - * \brief Pretty-print the underlying type using the rules of the + * Pretty-print the underlying type using the rules of the * language of the translation unit from which it came. * * If the type is invalid, an empty string is returned. @@ -3283,7 +3319,7 @@ CINDEX_LINKAGE CXType clang_getCursorType(CXCursor C); CINDEX_LINKAGE CXString clang_getTypeSpelling(CXType CT); /** - * \brief Retrieve the underlying type of a typedef declaration. + * Retrieve the underlying type of a typedef declaration. * * If the cursor does not reference a typedef declaration, an invalid type is * returned. @@ -3291,7 +3327,7 @@ CINDEX_LINKAGE CXString clang_getTypeSpelling(CXType CT); CINDEX_LINKAGE CXType clang_getTypedefDeclUnderlyingType(CXCursor C); /** - * \brief Retrieve the integer type of an enum declaration. + * Retrieve the integer type of an enum declaration. * * If the cursor does not reference an enum declaration, an invalid type is * returned. @@ -3299,7 +3335,7 @@ CINDEX_LINKAGE CXType clang_getTypedefDeclUnderlyingType(CXCursor C); CINDEX_LINKAGE CXType clang_getEnumDeclIntegerType(CXCursor C); /** - * \brief Retrieve the integer value of an enum constant declaration as a signed + * Retrieve the integer value of an enum constant declaration as a signed * long long. * * If the cursor does not reference an enum constant declaration, LLONG_MIN is returned. @@ -3309,7 +3345,7 @@ CINDEX_LINKAGE CXType clang_getEnumDeclIntegerType(CXCursor C); CINDEX_LINKAGE long long clang_getEnumConstantDeclValue(CXCursor C); /** - * \brief Retrieve the integer value of an enum constant declaration as an unsigned + * Retrieve the integer value of an enum constant declaration as an unsigned * long long. * * If the cursor does not reference an enum constant declaration, ULLONG_MAX is returned. @@ -3319,14 +3355,14 @@ CINDEX_LINKAGE long long clang_getEnumConstantDeclValue(CXCursor C); CINDEX_LINKAGE unsigned long long clang_getEnumConstantDeclUnsignedValue(CXCursor C); /** - * \brief Retrieve the bit width of a bit field declaration as an integer. + * Retrieve the bit width of a bit field declaration as an integer. * * If a cursor that is not a bit field declaration is passed in, -1 is returned. */ CINDEX_LINKAGE int clang_getFieldDeclBitWidth(CXCursor C); /** - * \brief Retrieve the number of non-variadic arguments associated with a given + * Retrieve the number of non-variadic arguments associated with a given * cursor. * * The number of arguments can be determined for calls as well as for @@ -3335,7 +3371,7 @@ CINDEX_LINKAGE int clang_getFieldDeclBitWidth(CXCursor C); CINDEX_LINKAGE int clang_Cursor_getNumArguments(CXCursor C); /** - * \brief Retrieve the argument cursor of a function or method. + * Retrieve the argument cursor of a function or method. * * The argument cursor can be determined for calls as well as for declarations * of functions or methods. For other cursors and for invalid indices, an @@ -3344,7 +3380,7 @@ CINDEX_LINKAGE int clang_Cursor_getNumArguments(CXCursor C); CINDEX_LINKAGE CXCursor clang_Cursor_getArgument(CXCursor C, unsigned i); /** - * \brief Describes the kind of a template argument. + * Describes the kind of a template argument. * * See the definition of llvm::clang::TemplateArgument::ArgKind for full * element descriptions. @@ -3364,7 +3400,7 @@ enum CXTemplateArgumentKind { }; /** - *\brief Returns the number of template args of a function decl representing a + *Returns the number of template args of a function decl representing a * template specialization. * * If the argument cursor cannot be converted into a template function @@ -3382,7 +3418,7 @@ enum CXTemplateArgumentKind { CINDEX_LINKAGE int clang_Cursor_getNumTemplateArguments(CXCursor C); /** - * \brief Retrieve the kind of the I'th template argument of the CXCursor C. + * Retrieve the kind of the I'th template argument of the CXCursor C. * * If the argument CXCursor does not represent a FunctionDecl, an invalid * template argument kind is returned. @@ -3401,7 +3437,7 @@ CINDEX_LINKAGE enum CXTemplateArgumentKind clang_Cursor_getTemplateArgumentKind( CXCursor C, unsigned I); /** - * \brief Retrieve a CXType representing the type of a TemplateArgument of a + * Retrieve a CXType representing the type of a TemplateArgument of a * function decl representing a template specialization. * * If the argument CXCursor does not represent a FunctionDecl whose I'th @@ -3422,7 +3458,7 @@ CINDEX_LINKAGE CXType clang_Cursor_getTemplateArgumentType(CXCursor C, unsigned I); /** - * \brief Retrieve the value of an Integral TemplateArgument (of a function + * Retrieve the value of an Integral TemplateArgument (of a function * decl representing a template specialization) as a signed long long. * * It is undefined to call this function on a CXCursor that does not represent a @@ -3442,7 +3478,7 @@ CINDEX_LINKAGE long long clang_Cursor_getTemplateArgumentValue(CXCursor C, unsigned I); /** - * \brief Retrieve the value of an Integral TemplateArgument (of a function + * Retrieve the value of an Integral TemplateArgument (of a function * decl representing a template specialization) as an unsigned long long. * * It is undefined to call this function on a CXCursor that does not represent a @@ -3462,7 +3498,7 @@ CINDEX_LINKAGE unsigned long long clang_Cursor_getTemplateArgumentUnsignedValue( CXCursor C, unsigned I); /** - * \brief Determine whether two CXTypes represent the same type. + * Determine whether two CXTypes represent the same type. * * \returns non-zero if the CXTypes represent the same type and * zero otherwise. @@ -3470,7 +3506,7 @@ CINDEX_LINKAGE unsigned long long clang_Cursor_getTemplateArgumentUnsignedValue( CINDEX_LINKAGE unsigned clang_equalTypes(CXType A, CXType B); /** - * \brief Return the canonical type for a CXType. + * Return the canonical type for a CXType. * * Clang's type system explicitly models typedefs and all the ways * a specific type can be represented. The canonical type is the underlying @@ -3480,61 +3516,61 @@ CINDEX_LINKAGE unsigned clang_equalTypes(CXType A, CXType B); CINDEX_LINKAGE CXType clang_getCanonicalType(CXType T); /** - * \brief Determine whether a CXType has the "const" qualifier set, + * Determine whether a CXType has the "const" qualifier set, * without looking through typedefs that may have added "const" at a * different level. */ CINDEX_LINKAGE unsigned clang_isConstQualifiedType(CXType T); /** - * \brief Determine whether a CXCursor that is a macro, is + * Determine whether a CXCursor that is a macro, is * function like. */ CINDEX_LINKAGE unsigned clang_Cursor_isMacroFunctionLike(CXCursor C); /** - * \brief Determine whether a CXCursor that is a macro, is a + * Determine whether a CXCursor that is a macro, is a * builtin one. */ CINDEX_LINKAGE unsigned clang_Cursor_isMacroBuiltin(CXCursor C); /** - * \brief Determine whether a CXCursor that is a function declaration, is an + * Determine whether a CXCursor that is a function declaration, is an * inline declaration. */ CINDEX_LINKAGE unsigned clang_Cursor_isFunctionInlined(CXCursor C); /** - * \brief Determine whether a CXType has the "volatile" qualifier set, + * Determine whether a CXType has the "volatile" qualifier set, * without looking through typedefs that may have added "volatile" at * a different level. */ CINDEX_LINKAGE unsigned clang_isVolatileQualifiedType(CXType T); /** - * \brief Determine whether a CXType has the "restrict" qualifier set, + * Determine whether a CXType has the "restrict" qualifier set, * without looking through typedefs that may have added "restrict" at a * different level. */ CINDEX_LINKAGE unsigned clang_isRestrictQualifiedType(CXType T); /** - * \brief Returns the address space of the given type. + * Returns the address space of the given type. */ CINDEX_LINKAGE unsigned clang_getAddressSpace(CXType T); /** - * \brief Returns the typedef name of the given type. + * Returns the typedef name of the given type. */ CINDEX_LINKAGE CXString clang_getTypedefName(CXType CT); /** - * \brief For pointer types, returns the type of the pointee. + * For pointer types, returns the type of the pointee. */ CINDEX_LINKAGE CXType clang_getPointeeType(CXType T); /** - * \brief Return the cursor for the declaration of the given type. + * Return the cursor for the declaration of the given type. */ CINDEX_LINKAGE CXCursor clang_getTypeDeclaration(CXType T); @@ -3549,33 +3585,34 @@ CINDEX_LINKAGE CXString clang_getDeclObjCTypeEncoding(CXCursor C); CINDEX_LINKAGE CXString clang_Type_getObjCEncoding(CXType type); /** - * \brief Retrieve the spelling of a given CXTypeKind. + * Retrieve the spelling of a given CXTypeKind. */ CINDEX_LINKAGE CXString clang_getTypeKindSpelling(enum CXTypeKind K); /** - * \brief Retrieve the calling convention associated with a function type. + * Retrieve the calling convention associated with a function type. * * If a non-function type is passed in, CXCallingConv_Invalid is returned. */ CINDEX_LINKAGE enum CXCallingConv clang_getFunctionTypeCallingConv(CXType T); /** - * \brief Retrieve the return type associated with a function type. + * Retrieve the return type associated with a function type. * * If a non-function type is passed in, an invalid type is returned. */ CINDEX_LINKAGE CXType clang_getResultType(CXType T); /** - * \brief Retrieve the exception specification type associated with a function type. + * Retrieve the exception specification type associated with a function type. + * This is a value of type CXCursor_ExceptionSpecificationKind. * * If a non-function type is passed in, an error code of -1 is returned. */ CINDEX_LINKAGE int clang_getExceptionSpecificationType(CXType T); /** - * \brief Retrieve the number of non-variadic parameters associated with a + * Retrieve the number of non-variadic parameters associated with a * function type. * * If a non-function type is passed in, -1 is returned. @@ -3583,7 +3620,7 @@ CINDEX_LINKAGE int clang_getExceptionSpecificationType(CXType T); CINDEX_LINKAGE int clang_getNumArgTypes(CXType T); /** - * \brief Retrieve the type of a parameter of a function type. + * Retrieve the type of a parameter of a function type. * * If a non-function type is passed in or the function does not have enough * parameters, an invalid type is returned. @@ -3591,32 +3628,33 @@ CINDEX_LINKAGE int clang_getNumArgTypes(CXType T); CINDEX_LINKAGE CXType clang_getArgType(CXType T, unsigned i); /** - * \brief Return 1 if the CXType is a variadic function type, and 0 otherwise. + * Return 1 if the CXType is a variadic function type, and 0 otherwise. */ CINDEX_LINKAGE unsigned clang_isFunctionTypeVariadic(CXType T); /** - * \brief Retrieve the return type associated with a given cursor. + * Retrieve the return type associated with a given cursor. * * This only returns a valid type if the cursor refers to a function or method. */ CINDEX_LINKAGE CXType clang_getCursorResultType(CXCursor C); /** - * \brief Retrieve the exception specification type associated with a given cursor. + * Retrieve the exception specification type associated with a given cursor. + * This is a value of type CXCursor_ExceptionSpecificationKind. * * This only returns a valid result if the cursor refers to a function or method. */ CINDEX_LINKAGE int clang_getCursorExceptionSpecificationType(CXCursor C); /** - * \brief Return 1 if the CXType is a POD (plain old data) type, and 0 + * Return 1 if the CXType is a POD (plain old data) type, and 0 * otherwise. */ CINDEX_LINKAGE unsigned clang_isPODType(CXType T); /** - * \brief Return the element type of an array, complex, or vector type. + * Return the element type of an array, complex, or vector type. * * If a type is passed in that is not an array, complex, or vector type, * an invalid type is returned. @@ -3624,7 +3662,7 @@ CINDEX_LINKAGE unsigned clang_isPODType(CXType T); CINDEX_LINKAGE CXType clang_getElementType(CXType T); /** - * \brief Return the number of elements of an array or vector type. + * Return the number of elements of an array or vector type. * * If a type is passed in that is not an array or vector type, * -1 is returned. @@ -3632,28 +3670,28 @@ CINDEX_LINKAGE CXType clang_getElementType(CXType T); CINDEX_LINKAGE long long clang_getNumElements(CXType T); /** - * \brief Return the element type of an array type. + * Return the element type of an array type. * * If a non-array type is passed in, an invalid type is returned. */ CINDEX_LINKAGE CXType clang_getArrayElementType(CXType T); /** - * \brief Return the array size of a constant array. + * Return the array size of a constant array. * * If a non-array type is passed in, -1 is returned. */ CINDEX_LINKAGE long long clang_getArraySize(CXType T); /** - * \brief Retrieve the type named by the qualified-id. + * Retrieve the type named by the qualified-id. * * If a non-elaborated type is passed in, an invalid type is returned. */ CINDEX_LINKAGE CXType clang_Type_getNamedType(CXType T); /** - * \brief Determine if a typedef is 'transparent' tag. + * Determine if a typedef is 'transparent' tag. * * A typedef is considered 'transparent' if it shares a name and spelling * location with its underlying tag type, as is the case with the NS_ENUM macro. @@ -3663,7 +3701,7 @@ CINDEX_LINKAGE CXType clang_Type_getNamedType(CXType T); CINDEX_LINKAGE unsigned clang_Type_isTransparentTagTypedef(CXType T); /** - * \brief List the possible error codes for \c clang_Type_getSizeOf, + * List the possible error codes for \c clang_Type_getSizeOf, * \c clang_Type_getAlignOf, \c clang_Type_getOffsetOf and * \c clang_Cursor_getOffsetOf. * @@ -3672,29 +3710,29 @@ CINDEX_LINKAGE unsigned clang_Type_isTransparentTagTypedef(CXType T); */ enum CXTypeLayoutError { /** - * \brief Type is of kind CXType_Invalid. + * Type is of kind CXType_Invalid. */ CXTypeLayoutError_Invalid = -1, /** - * \brief The type is an incomplete Type. + * The type is an incomplete Type. */ CXTypeLayoutError_Incomplete = -2, /** - * \brief The type is a dependent Type. + * The type is a dependent Type. */ CXTypeLayoutError_Dependent = -3, /** - * \brief The type is not a constant size type. + * The type is not a constant size type. */ CXTypeLayoutError_NotConstantSize = -4, /** - * \brief The Field name is not valid for this record. + * The Field name is not valid for this record. */ CXTypeLayoutError_InvalidFieldName = -5 }; /** - * \brief Return the alignment of a type in bytes as per C++[expr.alignof] + * Return the alignment of a type in bytes as per C++[expr.alignof] * standard. * * If the type declaration is invalid, CXTypeLayoutError_Invalid is returned. @@ -3708,14 +3746,14 @@ enum CXTypeLayoutError { CINDEX_LINKAGE long long clang_Type_getAlignOf(CXType T); /** - * \brief Return the class type of an member pointer type. + * Return the class type of an member pointer type. * * If a non-member-pointer type is passed in, an invalid type is returned. */ CINDEX_LINKAGE CXType clang_Type_getClassType(CXType T); /** - * \brief Return the size of a type in bytes as per C++[expr.sizeof] standard. + * Return the size of a type in bytes as per C++[expr.sizeof] standard. * * If the type declaration is invalid, CXTypeLayoutError_Invalid is returned. * If the type declaration is an incomplete type, CXTypeLayoutError_Incomplete @@ -3726,7 +3764,7 @@ CINDEX_LINKAGE CXType clang_Type_getClassType(CXType T); CINDEX_LINKAGE long long clang_Type_getSizeOf(CXType T); /** - * \brief Return the offset of a field named S in a record of type T in bits + * Return the offset of a field named S in a record of type T in bits * as it would be returned by __offsetof__ as per C++11[18.2p4] * * If the cursor is not a record field declaration, CXTypeLayoutError_Invalid @@ -3741,7 +3779,7 @@ CINDEX_LINKAGE long long clang_Type_getSizeOf(CXType T); CINDEX_LINKAGE long long clang_Type_getOffsetOf(CXType T, const char *S); /** - * \brief Return the offset of the field represented by the Cursor. + * Return the offset of the field represented by the Cursor. * * If the cursor is not a field declaration, -1 is returned. * If the cursor semantic parent is not a record field declaration, @@ -3756,28 +3794,28 @@ CINDEX_LINKAGE long long clang_Type_getOffsetOf(CXType T, const char *S); CINDEX_LINKAGE long long clang_Cursor_getOffsetOfField(CXCursor C); /** - * \brief Determine whether the given cursor represents an anonymous record + * Determine whether the given cursor represents an anonymous record * declaration. */ CINDEX_LINKAGE unsigned clang_Cursor_isAnonymous(CXCursor C); enum CXRefQualifierKind { - /** \brief No ref-qualifier was provided. */ + /** No ref-qualifier was provided. */ CXRefQualifier_None = 0, - /** \brief An lvalue ref-qualifier was provided (\c &). */ + /** An lvalue ref-qualifier was provided (\c &). */ CXRefQualifier_LValue, - /** \brief An rvalue ref-qualifier was provided (\c &&). */ + /** An rvalue ref-qualifier was provided (\c &&). */ CXRefQualifier_RValue }; /** - * \brief Returns the number of template arguments for given template + * Returns the number of template arguments for given template * specialization, or -1 if type \c T is not a template specialization. */ CINDEX_LINKAGE int clang_Type_getNumTemplateArguments(CXType T); /** - * \brief Returns the type template argument of a template class specialization + * Returns the type template argument of a template class specialization * at given index. * * This function only returns template type arguments and does not handle @@ -3786,7 +3824,7 @@ CINDEX_LINKAGE int clang_Type_getNumTemplateArguments(CXType T); CINDEX_LINKAGE CXType clang_Type_getTemplateArgumentAsType(CXType T, unsigned i); /** - * \brief Retrieve the ref-qualifier kind of a function or method. + * Retrieve the ref-qualifier kind of a function or method. * * The ref-qualifier is returned for C++ functions or methods. For other types * or non-C++ declarations, CXRefQualifier_None is returned. @@ -3794,19 +3832,19 @@ CINDEX_LINKAGE CXType clang_Type_getTemplateArgumentAsType(CXType T, unsigned i) CINDEX_LINKAGE enum CXRefQualifierKind clang_Type_getCXXRefQualifier(CXType T); /** - * \brief Returns non-zero if the cursor specifies a Record member that is a + * Returns non-zero if the cursor specifies a Record member that is a * bitfield. */ CINDEX_LINKAGE unsigned clang_Cursor_isBitField(CXCursor C); /** - * \brief Returns 1 if the base class specified by the cursor with kind + * Returns 1 if the base class specified by the cursor with kind * CX_CXXBaseSpecifier is virtual. */ CINDEX_LINKAGE unsigned clang_isVirtualBase(CXCursor); /** - * \brief Represents the C++ access control level to a base class for a + * Represents the C++ access control level to a base class for a * cursor with kind CX_CXXBaseSpecifier. */ enum CX_CXXAccessSpecifier { @@ -3817,7 +3855,7 @@ enum CX_CXXAccessSpecifier { }; /** - * \brief Returns the access control level for the referenced object. + * Returns the access control level for the referenced object. * * If the cursor refers to a C++ declaration, its access control level within its * parent scope is returned. Otherwise, if the cursor refers to a base specifier or @@ -3826,7 +3864,7 @@ enum CX_CXXAccessSpecifier { CINDEX_LINKAGE enum CX_CXXAccessSpecifier clang_getCXXAccessSpecifier(CXCursor); /** - * \brief Represents the storage classes as declared in the source. CX_SC_Invalid + * Represents the storage classes as declared in the source. CX_SC_Invalid * was added for the case that the passed cursor in not a declaration. */ enum CX_StorageClass { @@ -3841,7 +3879,7 @@ enum CX_StorageClass { }; /** - * \brief Returns the storage class for a function or variable declaration. + * Returns the storage class for a function or variable declaration. * * If the passed in Cursor is not a function or variable declaration, * CX_SC_Invalid is returned else the storage class. @@ -3849,7 +3887,7 @@ enum CX_StorageClass { CINDEX_LINKAGE enum CX_StorageClass clang_Cursor_getStorageClass(CXCursor); /** - * \brief Determine the number of overloaded declarations referenced by a + * Determine the number of overloaded declarations referenced by a * \c CXCursor_OverloadedDeclRef cursor. * * \param cursor The cursor whose overloaded declarations are being queried. @@ -3860,7 +3898,7 @@ CINDEX_LINKAGE enum CX_StorageClass clang_Cursor_getStorageClass(CXCursor); CINDEX_LINKAGE unsigned clang_getNumOverloadedDecls(CXCursor cursor); /** - * \brief Retrieve a cursor for one of the overloaded declarations referenced + * Retrieve a cursor for one of the overloaded declarations referenced * by a \c CXCursor_OverloadedDeclRef cursor. * * \param cursor The cursor whose overloaded declarations are being queried. @@ -3887,7 +3925,7 @@ CINDEX_LINKAGE CXCursor clang_getOverloadedDecl(CXCursor cursor, */ /** - * \brief For cursors representing an iboutletcollection attribute, + * For cursors representing an iboutletcollection attribute, * this function returns the collection element type. * */ @@ -3907,7 +3945,7 @@ CINDEX_LINKAGE CXType clang_getIBOutletCollectionType(CXCursor); */ /** - * \brief Describes how the traversal of the children of a particular + * Describes how the traversal of the children of a particular * cursor should proceed after visiting a particular child cursor. * * A value of this enumeration type should be returned by each @@ -3915,23 +3953,23 @@ CINDEX_LINKAGE CXType clang_getIBOutletCollectionType(CXCursor); */ enum CXChildVisitResult { /** - * \brief Terminates the cursor traversal. + * Terminates the cursor traversal. */ CXChildVisit_Break, /** - * \brief Continues the cursor traversal with the next sibling of + * Continues the cursor traversal with the next sibling of * the cursor just visited, without visiting its children. */ CXChildVisit_Continue, /** - * \brief Recursively traverse the children of this cursor, using + * Recursively traverse the children of this cursor, using * the same visitor and client data. */ CXChildVisit_Recurse }; /** - * \brief Visitor invoked for each cursor found by a traversal. + * Visitor invoked for each cursor found by a traversal. * * This visitor function will be invoked for each cursor found by * clang_visitCursorChildren(). Its first argument is the cursor being @@ -3947,7 +3985,7 @@ typedef enum CXChildVisitResult (*CXCursorVisitor)(CXCursor cursor, CXClientData client_data); /** - * \brief Visit the children of a particular cursor. + * Visit the children of a particular cursor. * * This function visits all the direct children of the given cursor, * invoking the given \p visitor function with the cursors of each @@ -3974,7 +4012,7 @@ CINDEX_LINKAGE unsigned clang_visitChildren(CXCursor parent, #ifdef __has_feature # if __has_feature(blocks) /** - * \brief Visitor invoked for each cursor found by a traversal. + * Visitor invoked for each cursor found by a traversal. * * This visitor block will be invoked for each cursor found by * clang_visitChildrenWithBlock(). Its first argument is the cursor being @@ -4011,7 +4049,7 @@ CINDEX_LINKAGE unsigned clang_visitChildrenWithBlock(CXCursor parent, */ /** - * \brief Retrieve a Unified Symbol Resolution (USR) for the entity referenced + * Retrieve a Unified Symbol Resolution (USR) for the entity referenced * by the given cursor. * * A Unified Symbol Resolution (USR) is a string that identifies a particular @@ -4022,32 +4060,32 @@ CINDEX_LINKAGE unsigned clang_visitChildrenWithBlock(CXCursor parent, CINDEX_LINKAGE CXString clang_getCursorUSR(CXCursor); /** - * \brief Construct a USR for a specified Objective-C class. + * Construct a USR for a specified Objective-C class. */ CINDEX_LINKAGE CXString clang_constructUSR_ObjCClass(const char *class_name); /** - * \brief Construct a USR for a specified Objective-C category. + * Construct a USR for a specified Objective-C category. */ CINDEX_LINKAGE CXString clang_constructUSR_ObjCCategory(const char *class_name, const char *category_name); /** - * \brief Construct a USR for a specified Objective-C protocol. + * Construct a USR for a specified Objective-C protocol. */ CINDEX_LINKAGE CXString clang_constructUSR_ObjCProtocol(const char *protocol_name); /** - * \brief Construct a USR for a specified Objective-C instance variable and + * Construct a USR for a specified Objective-C instance variable and * the USR for its containing class. */ CINDEX_LINKAGE CXString clang_constructUSR_ObjCIvar(const char *name, CXString classUSR); /** - * \brief Construct a USR for a specified Objective-C method and + * Construct a USR for a specified Objective-C method and * the USR for its containing class. */ CINDEX_LINKAGE CXString clang_constructUSR_ObjCMethod(const char *name, @@ -4055,19 +4093,19 @@ CINDEX_LINKAGE CXString clang_constructUSR_ObjCMethod(const char *name, CXString classUSR); /** - * \brief Construct a USR for a specified Objective-C property and the USR + * Construct a USR for a specified Objective-C property and the USR * for its containing class. */ CINDEX_LINKAGE CXString clang_constructUSR_ObjCProperty(const char *property, CXString classUSR); /** - * \brief Retrieve a name for the entity referenced by this cursor. + * Retrieve a name for the entity referenced by this cursor. */ CINDEX_LINKAGE CXString clang_getCursorSpelling(CXCursor); /** - * \brief Retrieve a range for a piece that forms the cursors spelling name. + * Retrieve a range for a piece that forms the cursors spelling name. * Most of the times there is only one range for the complete spelling but for * Objective-C methods and Objective-C message expressions, there are multiple * pieces for each selector identifier. @@ -4082,7 +4120,90 @@ CINDEX_LINKAGE CXSourceRange clang_Cursor_getSpellingNameRange(CXCursor, unsigned options); /** - * \brief Retrieve the display name for the entity referenced by this cursor. + * Opaque pointer representing a policy that controls pretty printing + * for \c clang_getCursorPrettyPrinted. + */ +typedef void *CXPrintingPolicy; + +/** + * Properties for the printing policy. + * + * See \c clang::PrintingPolicy for more information. + */ +enum CXPrintingPolicyProperty { + CXPrintingPolicy_Indentation, + CXPrintingPolicy_SuppressSpecifiers, + CXPrintingPolicy_SuppressTagKeyword, + CXPrintingPolicy_IncludeTagDefinition, + CXPrintingPolicy_SuppressScope, + CXPrintingPolicy_SuppressUnwrittenScope, + CXPrintingPolicy_SuppressInitializers, + CXPrintingPolicy_ConstantArraySizeAsWritten, + CXPrintingPolicy_AnonymousTagLocations, + CXPrintingPolicy_SuppressStrongLifetime, + CXPrintingPolicy_SuppressLifetimeQualifiers, + CXPrintingPolicy_SuppressTemplateArgsInCXXConstructors, + CXPrintingPolicy_Bool, + CXPrintingPolicy_Restrict, + CXPrintingPolicy_Alignof, + CXPrintingPolicy_UnderscoreAlignof, + CXPrintingPolicy_UseVoidForZeroParams, + CXPrintingPolicy_TerseOutput, + CXPrintingPolicy_PolishForDeclaration, + CXPrintingPolicy_Half, + CXPrintingPolicy_MSWChar, + CXPrintingPolicy_IncludeNewlines, + CXPrintingPolicy_MSVCFormatting, + CXPrintingPolicy_ConstantsAsWritten, + CXPrintingPolicy_SuppressImplicitBase, + CXPrintingPolicy_FullyQualifiedName, + + CXPrintingPolicy_LastProperty = CXPrintingPolicy_FullyQualifiedName +}; + +/** + * Get a property value for the given printing policy. + */ +CINDEX_LINKAGE unsigned +clang_PrintingPolicy_getProperty(CXPrintingPolicy Policy, + enum CXPrintingPolicyProperty Property); + +/** + * Set a property value for the given printing policy. + */ +CINDEX_LINKAGE void clang_PrintingPolicy_setProperty(CXPrintingPolicy Policy, + enum CXPrintingPolicyProperty Property, + unsigned Value); + +/** + * Retrieve the default policy for the cursor. + * + * The policy should be released after use with \c + * clang_PrintingPolicy_dispose. + */ +CINDEX_LINKAGE CXPrintingPolicy clang_getCursorPrintingPolicy(CXCursor); + +/** + * Release a printing policy. + */ +CINDEX_LINKAGE void clang_PrintingPolicy_dispose(CXPrintingPolicy Policy); + +/** + * Pretty print declarations. + * + * \param Cursor The cursor representing a declaration. + * + * \param Policy The policy to control the entities being printed. If + * NULL, a default policy is used. + * + * \returns The pretty printed declaration or the empty string for + * other cursors. + */ +CINDEX_LINKAGE CXString clang_getCursorPrettyPrinted(CXCursor Cursor, + CXPrintingPolicy Policy); + +/** + * Retrieve the display name for the entity referenced by this cursor. * * The display name contains extra information that helps identify the cursor, * such as the parameters of a function or template or the arguments of a @@ -4090,7 +4211,7 @@ CINDEX_LINKAGE CXSourceRange clang_Cursor_getSpellingNameRange(CXCursor, */ CINDEX_LINKAGE CXString clang_getCursorDisplayName(CXCursor); -/** \brief For a cursor that is a reference, retrieve a cursor representing the +/** For a cursor that is a reference, retrieve a cursor representing the * entity that it references. * * Reference cursors refer to other entities in the AST. For example, an @@ -4103,7 +4224,7 @@ CINDEX_LINKAGE CXString clang_getCursorDisplayName(CXCursor); CINDEX_LINKAGE CXCursor clang_getCursorReferenced(CXCursor); /** - * \brief For a cursor that is either a reference to or a declaration + * For a cursor that is either a reference to or a declaration * of some entity, retrieve a cursor that describes the definition of * that entity. * @@ -4133,13 +4254,13 @@ CINDEX_LINKAGE CXCursor clang_getCursorReferenced(CXCursor); CINDEX_LINKAGE CXCursor clang_getCursorDefinition(CXCursor); /** - * \brief Determine whether the declaration pointed to by this cursor + * Determine whether the declaration pointed to by this cursor * is also a definition of that entity. */ CINDEX_LINKAGE unsigned clang_isCursorDefinition(CXCursor); /** - * \brief Retrieve the canonical cursor corresponding to the given cursor. + * Retrieve the canonical cursor corresponding to the given cursor. * * In the C family of languages, many kinds of entities can be declared several * times within a single translation unit. For example, a structure type can @@ -4165,7 +4286,7 @@ CINDEX_LINKAGE unsigned clang_isCursorDefinition(CXCursor); CINDEX_LINKAGE CXCursor clang_getCanonicalCursor(CXCursor); /** - * \brief If the cursor points to a selector identifier in an Objective-C + * If the cursor points to a selector identifier in an Objective-C * method or message expression, this returns the selector index. * * After getting a cursor with #clang_getCursor, this can be called to @@ -4178,7 +4299,7 @@ CINDEX_LINKAGE CXCursor clang_getCanonicalCursor(CXCursor); CINDEX_LINKAGE int clang_Cursor_getObjCSelectorIndex(CXCursor); /** - * \brief Given a cursor pointing to a C++ method call or an Objective-C + * Given a cursor pointing to a C++ method call or an Objective-C * message, returns non-zero if the method/message is "dynamic", meaning: * * For a C++ method: the call is virtual. @@ -4191,13 +4312,13 @@ CINDEX_LINKAGE int clang_Cursor_getObjCSelectorIndex(CXCursor); CINDEX_LINKAGE int clang_Cursor_isDynamicCall(CXCursor C); /** - * \brief Given a cursor pointing to an Objective-C message or property + * Given a cursor pointing to an Objective-C message or property * reference, or C++ method call, returns the CXType of the receiver. */ CINDEX_LINKAGE CXType clang_Cursor_getReceiverType(CXCursor C); /** - * \brief Property attributes for a \c CXCursor_ObjCPropertyDecl. + * Property attributes for a \c CXCursor_ObjCPropertyDecl. */ typedef enum { CXObjCPropertyAttr_noattr = 0x00, @@ -4217,7 +4338,7 @@ typedef enum { } CXObjCPropertyAttrKind; /** - * \brief Given a cursor that represents a property declaration, return the + * Given a cursor that represents a property declaration, return the * associated property attributes. The bits are formed from * \c CXObjCPropertyAttrKind. * @@ -4227,7 +4348,7 @@ CINDEX_LINKAGE unsigned clang_Cursor_getObjCPropertyAttributes(CXCursor C, unsigned reserved); /** - * \brief 'Qualifiers' written next to the return and parameter types in + * 'Qualifiers' written next to the return and parameter types in * Objective-C method declarations. */ typedef enum { @@ -4241,7 +4362,7 @@ typedef enum { } CXObjCDeclQualifierKind; /** - * \brief Given a cursor that represents an Objective-C method or parameter + * Given a cursor that represents an Objective-C method or parameter * declaration, return the associated Objective-C qualifiers for the return * type or the parameter respectively. The bits are formed from * CXObjCDeclQualifierKind. @@ -4249,19 +4370,19 @@ typedef enum { CINDEX_LINKAGE unsigned clang_Cursor_getObjCDeclQualifiers(CXCursor C); /** - * \brief Given a cursor that represents an Objective-C method or property + * Given a cursor that represents an Objective-C method or property * declaration, return non-zero if the declaration was affected by "\@optional". * Returns zero if the cursor is not such a declaration or it is "\@required". */ CINDEX_LINKAGE unsigned clang_Cursor_isObjCOptional(CXCursor C); /** - * \brief Returns non-zero if the given cursor is a variadic function or method. + * Returns non-zero if the given cursor is a variadic function or method. */ CINDEX_LINKAGE unsigned clang_Cursor_isVariadic(CXCursor C); /** - * \brief Returns non-zero if the given cursor points to a symbol marked with + * Returns non-zero if the given cursor points to a symbol marked with * external_source_symbol attribute. * * \param language If non-NULL, and the attribute is present, will be set to @@ -4278,21 +4399,21 @@ CINDEX_LINKAGE unsigned clang_Cursor_isExternalSymbol(CXCursor C, unsigned *isGenerated); /** - * \brief Given a cursor that represents a declaration, return the associated + * Given a cursor that represents a declaration, return the associated * comment's source range. The range may include multiple consecutive comments * with whitespace in between. */ CINDEX_LINKAGE CXSourceRange clang_Cursor_getCommentRange(CXCursor C); /** - * \brief Given a cursor that represents a declaration, return the associated + * Given a cursor that represents a declaration, return the associated * comment text, including comment markers. */ CINDEX_LINKAGE CXString clang_Cursor_getRawCommentText(CXCursor C); /** - * \brief Given a cursor that represents a documentable entity (e.g., - * declaration), return the associated \\brief paragraph; otherwise return the + * Given a cursor that represents a documentable entity (e.g., + * declaration), return the associated \paragraph; otherwise return the * first paragraph. */ CINDEX_LINKAGE CXString clang_Cursor_getBriefCommentText(CXCursor C); @@ -4307,18 +4428,18 @@ CINDEX_LINKAGE CXString clang_Cursor_getBriefCommentText(CXCursor C); */ /** - * \brief Retrieve the CXString representing the mangled name of the cursor. + * Retrieve the CXString representing the mangled name of the cursor. */ CINDEX_LINKAGE CXString clang_Cursor_getMangling(CXCursor); /** - * \brief Retrieve the CXStrings representing the mangled symbols of the C++ + * Retrieve the CXStrings representing the mangled symbols of the C++ * constructor or destructor at the cursor. */ CINDEX_LINKAGE CXStringSet *clang_Cursor_getCXXManglings(CXCursor); /** - * \brief Retrieve the CXStrings representing the mangled symbols of the ObjC + * Retrieve the CXStrings representing the mangled symbols of the ObjC * class interface or implementation at the cursor. */ CINDEX_LINKAGE CXStringSet *clang_Cursor_getObjCManglings(CXCursor); @@ -4338,12 +4459,12 @@ CINDEX_LINKAGE CXStringSet *clang_Cursor_getObjCManglings(CXCursor); typedef void *CXModule; /** - * \brief Given a CXCursor_ModuleImportDecl cursor, return the associated module. + * Given a CXCursor_ModuleImportDecl cursor, return the associated module. */ CINDEX_LINKAGE CXModule clang_Cursor_getModule(CXCursor C); /** - * \brief Given a CXFile header file, return the module that contains it, if one + * Given a CXFile header file, return the module that contains it, if one * exists. */ CINDEX_LINKAGE CXModule clang_getModuleForFile(CXTranslationUnit, CXFile); @@ -4418,73 +4539,73 @@ CXFile clang_Module_getTopLevelHeader(CXTranslationUnit, */ /** - * \brief Determine if a C++ constructor is a converting constructor. + * Determine if a C++ constructor is a converting constructor. */ CINDEX_LINKAGE unsigned clang_CXXConstructor_isConvertingConstructor(CXCursor C); /** - * \brief Determine if a C++ constructor is a copy constructor. + * Determine if a C++ constructor is a copy constructor. */ CINDEX_LINKAGE unsigned clang_CXXConstructor_isCopyConstructor(CXCursor C); /** - * \brief Determine if a C++ constructor is the default constructor. + * Determine if a C++ constructor is the default constructor. */ CINDEX_LINKAGE unsigned clang_CXXConstructor_isDefaultConstructor(CXCursor C); /** - * \brief Determine if a C++ constructor is a move constructor. + * Determine if a C++ constructor is a move constructor. */ CINDEX_LINKAGE unsigned clang_CXXConstructor_isMoveConstructor(CXCursor C); /** - * \brief Determine if a C++ field is declared 'mutable'. + * Determine if a C++ field is declared 'mutable'. */ CINDEX_LINKAGE unsigned clang_CXXField_isMutable(CXCursor C); /** - * \brief Determine if a C++ method is declared '= default'. + * Determine if a C++ method is declared '= default'. */ CINDEX_LINKAGE unsigned clang_CXXMethod_isDefaulted(CXCursor C); /** - * \brief Determine if a C++ member function or member function template is + * Determine if a C++ member function or member function template is * pure virtual. */ CINDEX_LINKAGE unsigned clang_CXXMethod_isPureVirtual(CXCursor C); /** - * \brief Determine if a C++ member function or member function template is + * Determine if a C++ member function or member function template is * declared 'static'. */ CINDEX_LINKAGE unsigned clang_CXXMethod_isStatic(CXCursor C); /** - * \brief Determine if a C++ member function or member function template is + * Determine if a C++ member function or member function template is * explicitly declared 'virtual' or if it overrides a virtual method from * one of the base classes. */ CINDEX_LINKAGE unsigned clang_CXXMethod_isVirtual(CXCursor C); /** - * \brief Determine if a C++ record is abstract, i.e. whether a class or struct + * Determine if a C++ record is abstract, i.e. whether a class or struct * has a pure virtual member function. */ CINDEX_LINKAGE unsigned clang_CXXRecord_isAbstract(CXCursor C); /** - * \brief Determine if an enum declaration refers to a scoped enum. + * Determine if an enum declaration refers to a scoped enum. */ CINDEX_LINKAGE unsigned clang_EnumDecl_isScoped(CXCursor C); /** - * \brief Determine if a C++ member function or member function template is + * Determine if a C++ member function or member function template is * declared 'const'. */ CINDEX_LINKAGE unsigned clang_CXXMethod_isConst(CXCursor C); /** - * \brief Given a cursor that represents a template, determine + * Given a cursor that represents a template, determine * the cursor kind of the specializations would be generated by instantiating * the template. * @@ -4503,7 +4624,7 @@ CINDEX_LINKAGE unsigned clang_CXXMethod_isConst(CXCursor C); CINDEX_LINKAGE enum CXCursorKind clang_getTemplateCursorKind(CXCursor C); /** - * \brief Given a cursor that may represent a specialization or instantiation + * Given a cursor that may represent a specialization or instantiation * of a template, retrieve the cursor that represents the template that it * specializes or from which it was instantiated. * @@ -4533,7 +4654,7 @@ CINDEX_LINKAGE enum CXCursorKind clang_getTemplateCursorKind(CXCursor C); CINDEX_LINKAGE CXCursor clang_getSpecializedCursorTemplate(CXCursor C); /** - * \brief Given a cursor that references something else, return the source range + * Given a cursor that references something else, return the source range * covering that reference. * * \param C A cursor pointing to a member reference, a declaration reference, or @@ -4556,19 +4677,19 @@ CINDEX_LINKAGE CXSourceRange clang_getCursorReferenceNameRange(CXCursor C, enum CXNameRefFlags { /** - * \brief Include the nested-name-specifier, e.g. Foo:: in x.Foo::y, in the + * Include the nested-name-specifier, e.g. Foo:: in x.Foo::y, in the * range. */ CXNameRange_WantQualifier = 0x1, /** - * \brief Include the explicit template arguments, e.g. \<int> in x.f<int>, + * Include the explicit template arguments, e.g. \<int> in x.f<int>, * in the range. */ CXNameRange_WantTemplateArgs = 0x2, /** - * \brief If the name is non-contiguous, return the full spanning range. + * If the name is non-contiguous, return the full spanning range. * * Non-contiguous names occur in Objective-C when a selector with two or more * parameters is used, or in C++ when using an operator: @@ -4595,37 +4716,37 @@ enum CXNameRefFlags { */ /** - * \brief Describes a kind of token. + * Describes a kind of token. */ typedef enum CXTokenKind { /** - * \brief A token that contains some kind of punctuation. + * A token that contains some kind of punctuation. */ CXToken_Punctuation, /** - * \brief A language keyword. + * A language keyword. */ CXToken_Keyword, /** - * \brief An identifier (that is not a keyword). + * An identifier (that is not a keyword). */ CXToken_Identifier, /** - * \brief A numeric, string, or character literal. + * A numeric, string, or character literal. */ CXToken_Literal, /** - * \brief A comment. + * A comment. */ CXToken_Comment } CXTokenKind; /** - * \brief Describes a single preprocessing token. + * Describes a single preprocessing token. */ typedef struct { unsigned int_data[4]; @@ -4633,12 +4754,26 @@ typedef struct { } CXToken; /** - * \brief Determine the kind of the given token. + * Get the raw lexical token starting with the given location. + * + * \param TU the translation unit whose text is being tokenized. + * + * \param Location the source location with which the token starts. + * + * \returns The token starting with the given location or NULL if no such token + * exist. The returned pointer must be freed with clang_disposeTokens before the + * translation unit is destroyed. + */ +CINDEX_LINKAGE CXToken *clang_getToken(CXTranslationUnit TU, + CXSourceLocation Location); + +/** + * Determine the kind of the given token. */ CINDEX_LINKAGE CXTokenKind clang_getTokenKind(CXToken); /** - * \brief Determine the spelling of the given token. + * Determine the spelling of the given token. * * The spelling of a token is the textual representation of that token, e.g., * the text of an identifier or keyword. @@ -4646,18 +4781,18 @@ CINDEX_LINKAGE CXTokenKind clang_getTokenKind(CXToken); CINDEX_LINKAGE CXString clang_getTokenSpelling(CXTranslationUnit, CXToken); /** - * \brief Retrieve the source location of the given token. + * Retrieve the source location of the given token. */ CINDEX_LINKAGE CXSourceLocation clang_getTokenLocation(CXTranslationUnit, CXToken); /** - * \brief Retrieve a source range that covers the given token. + * Retrieve a source range that covers the given token. */ CINDEX_LINKAGE CXSourceRange clang_getTokenExtent(CXTranslationUnit, CXToken); /** - * \brief Tokenize the source code described by the given range into raw + * Tokenize the source code described by the given range into raw * lexical tokens. * * \param TU the translation unit whose text is being tokenized. @@ -4677,7 +4812,7 @@ CINDEX_LINKAGE void clang_tokenize(CXTranslationUnit TU, CXSourceRange Range, CXToken **Tokens, unsigned *NumTokens); /** - * \brief Annotate the given set of tokens by providing cursors for each token + * Annotate the given set of tokens by providing cursors for each token * that can be mapped to a specific entity within the abstract syntax tree. * * This token-annotation routine is equivalent to invoking @@ -4711,7 +4846,7 @@ CINDEX_LINKAGE void clang_annotateTokens(CXTranslationUnit TU, CXCursor *Cursors); /** - * \brief Free the given set of tokens. + * Free the given set of tokens. */ CINDEX_LINKAGE void clang_disposeTokens(CXTranslationUnit TU, CXToken *Tokens, unsigned NumTokens); @@ -4759,7 +4894,7 @@ CINDEX_LINKAGE void clang_executeOnThread(void (*fn)(void*), void *user_data, */ /** - * \brief A semantic string that describes a code-completion result. + * A semantic string that describes a code-completion result. * * A semantic string that describes the formatting of a code-completion * result as a single "template" of text that should be inserted into the @@ -4774,11 +4909,11 @@ CINDEX_LINKAGE void clang_executeOnThread(void (*fn)(void*), void *user_data, typedef void *CXCompletionString; /** - * \brief A single result of code completion. + * A single result of code completion. */ typedef struct { /** - * \brief The kind of entity that this completion refers to. + * The kind of entity that this completion refers to. * * The cursor kind will be a macro, keyword, or a declaration (one of the * *Decl cursor kinds), describing the entity that the completion is @@ -4790,14 +4925,14 @@ typedef struct { enum CXCursorKind CursorKind; /** - * \brief The code-completion string that describes how to insert this + * The code-completion string that describes how to insert this * code-completion result into the editing buffer. */ CXCompletionString CompletionString; } CXCompletionResult; /** - * \brief Describes a single piece of text within a code-completion string. + * Describes a single piece of text within a code-completion string. * * Each "chunk" within a code-completion string (\c CXCompletionString) is * either a piece of text with a specific "kind" that describes how that text @@ -4805,7 +4940,7 @@ typedef struct { */ enum CXCompletionChunkKind { /** - * \brief A code-completion string that describes "optional" text that + * A code-completion string that describes "optional" text that * could be a part of the template (but is not required). * * The Optional chunk is the only kind of chunk that has a code-completion @@ -4839,7 +4974,7 @@ enum CXCompletionChunkKind { */ CXCompletionChunk_Optional, /** - * \brief Text that a user would be expected to type to get this + * Text that a user would be expected to type to get this * code-completion result. * * There will be exactly one "typed text" chunk in a semantic string, which @@ -4850,7 +4985,7 @@ enum CXCompletionChunkKind { */ CXCompletionChunk_TypedText, /** - * \brief Text that should be inserted as part of a code-completion result. + * Text that should be inserted as part of a code-completion result. * * A "text" chunk represents text that is part of the template to be * inserted into user code should this particular code-completion result @@ -4858,7 +4993,7 @@ enum CXCompletionChunkKind { */ CXCompletionChunk_Text, /** - * \brief Placeholder text that should be replaced by the user. + * Placeholder text that should be replaced by the user. * * A "placeholder" chunk marks a place where the user should insert text * into the code-completion template. For example, placeholders might mark @@ -4869,7 +5004,7 @@ enum CXCompletionChunkKind { */ CXCompletionChunk_Placeholder, /** - * \brief Informative text that should be displayed but never inserted as + * Informative text that should be displayed but never inserted as * part of the template. * * An "informative" chunk contains annotations that can be displayed to @@ -4879,7 +5014,7 @@ enum CXCompletionChunkKind { */ CXCompletionChunk_Informative, /** - * \brief Text that describes the current parameter when code-completion is + * Text that describes the current parameter when code-completion is * referring to function call, message send, or template specialization. * * A "current parameter" chunk occurs when code-completion is providing @@ -4895,49 +5030,49 @@ enum CXCompletionChunkKind { * for "int x", indicating that the current argument will initialize that * parameter. After typing further, to \c add(17, (where the code-completion * point is after the ","), the code-completion string will contain a - * "current paremeter" chunk to "int y". + * "current parameter" chunk to "int y". */ CXCompletionChunk_CurrentParameter, /** - * \brief A left parenthesis ('('), used to initiate a function call or + * A left parenthesis ('('), used to initiate a function call or * signal the beginning of a function parameter list. */ CXCompletionChunk_LeftParen, /** - * \brief A right parenthesis (')'), used to finish a function call or + * A right parenthesis (')'), used to finish a function call or * signal the end of a function parameter list. */ CXCompletionChunk_RightParen, /** - * \brief A left bracket ('['). + * A left bracket ('['). */ CXCompletionChunk_LeftBracket, /** - * \brief A right bracket (']'). + * A right bracket (']'). */ CXCompletionChunk_RightBracket, /** - * \brief A left brace ('{'). + * A left brace ('{'). */ CXCompletionChunk_LeftBrace, /** - * \brief A right brace ('}'). + * A right brace ('}'). */ CXCompletionChunk_RightBrace, /** - * \brief A left angle bracket ('<'). + * A left angle bracket ('<'). */ CXCompletionChunk_LeftAngle, /** - * \brief A right angle bracket ('>'). + * A right angle bracket ('>'). */ CXCompletionChunk_RightAngle, /** - * \brief A comma separator (','). + * A comma separator (','). */ CXCompletionChunk_Comma, /** - * \brief Text that specifies the result type of a given result. + * Text that specifies the result type of a given result. * * This special kind of informative chunk is not meant to be inserted into * the text buffer. Rather, it is meant to illustrate the type that an @@ -4945,15 +5080,15 @@ enum CXCompletionChunkKind { */ CXCompletionChunk_ResultType, /** - * \brief A colon (':'). + * A colon (':'). */ CXCompletionChunk_Colon, /** - * \brief A semicolon (';'). + * A semicolon (';'). */ CXCompletionChunk_SemiColon, /** - * \brief An '=' sign. + * An '=' sign. */ CXCompletionChunk_Equal, /** @@ -4968,7 +5103,7 @@ enum CXCompletionChunkKind { }; /** - * \brief Determine the kind of a particular chunk within a completion string. + * Determine the kind of a particular chunk within a completion string. * * \param completion_string the completion string to query. * @@ -4981,7 +5116,7 @@ clang_getCompletionChunkKind(CXCompletionString completion_string, unsigned chunk_number); /** - * \brief Retrieve the text associated with a particular chunk within a + * Retrieve the text associated with a particular chunk within a * completion string. * * \param completion_string the completion string to query. @@ -4995,7 +5130,7 @@ clang_getCompletionChunkText(CXCompletionString completion_string, unsigned chunk_number); /** - * \brief Retrieve the completion string associated with a particular chunk + * Retrieve the completion string associated with a particular chunk * within a completion string. * * \param completion_string the completion string to query. @@ -5010,13 +5145,13 @@ clang_getCompletionChunkCompletionString(CXCompletionString completion_string, unsigned chunk_number); /** - * \brief Retrieve the number of chunks in the given code-completion string. + * Retrieve the number of chunks in the given code-completion string. */ CINDEX_LINKAGE unsigned clang_getNumCompletionChunks(CXCompletionString completion_string); /** - * \brief Determine the priority of this code completion. + * Determine the priority of this code completion. * * The priority of a code completion indicates how likely it is that this * particular completion is the completion that the user will select. The @@ -5031,7 +5166,7 @@ CINDEX_LINKAGE unsigned clang_getCompletionPriority(CXCompletionString completion_string); /** - * \brief Determine the availability of the entity that this code-completion + * Determine the availability of the entity that this code-completion * string refers to. * * \param completion_string The completion string to query. @@ -5042,7 +5177,7 @@ CINDEX_LINKAGE enum CXAvailabilityKind clang_getCompletionAvailability(CXCompletionString completion_string); /** - * \brief Retrieve the number of annotations associated with the given + * Retrieve the number of annotations associated with the given * completion string. * * \param completion_string the completion string to query. @@ -5054,7 +5189,7 @@ CINDEX_LINKAGE unsigned clang_getCompletionNumAnnotations(CXCompletionString completion_string); /** - * \brief Retrieve the annotation associated with the given completion string. + * Retrieve the annotation associated with the given completion string. * * \param completion_string the completion string to query. * @@ -5069,7 +5204,7 @@ clang_getCompletionAnnotation(CXCompletionString completion_string, unsigned annotation_number); /** - * \brief Retrieve the parent context of the given completion string. + * Retrieve the parent context of the given completion string. * * The parent context of a completion string is the semantic parent of * the declaration (if any) that the code completion represents. For example, @@ -5089,14 +5224,14 @@ clang_getCompletionParent(CXCompletionString completion_string, enum CXCursorKind *kind); /** - * \brief Retrieve the brief documentation comment attached to the declaration + * Retrieve the brief documentation comment attached to the declaration * that corresponds to the given completion string. */ CINDEX_LINKAGE CXString clang_getCompletionBriefComment(CXCompletionString completion_string); /** - * \brief Retrieve a completion string for an arbitrary declaration or macro + * Retrieve a completion string for an arbitrary declaration or macro * definition cursor. * * \param cursor The cursor to query. @@ -5108,7 +5243,7 @@ CINDEX_LINKAGE CXCompletionString clang_getCursorCompletionString(CXCursor cursor); /** - * \brief Contains the results of code-completion. + * Contains the results of code-completion. * * This data structure contains the results of code completion, as * produced by \c clang_codeCompleteAt(). Its contents must be freed by @@ -5116,19 +5251,83 @@ clang_getCursorCompletionString(CXCursor cursor); */ typedef struct { /** - * \brief The code-completion results. + * The code-completion results. */ CXCompletionResult *Results; /** - * \brief The number of code-completion results stored in the + * The number of code-completion results stored in the * \c Results array. */ unsigned NumResults; } CXCodeCompleteResults; /** - * \brief Flags that can be passed to \c clang_codeCompleteAt() to + * Retrieve the number of fix-its for the given completion index. + * + * Calling this makes sense only if CXCodeComplete_IncludeCompletionsWithFixIts + * option was set. + * + * \param results The structure keeping all completion results + * + * \param completion_index The index of the completion + * + * \return The number of fix-its which must be applied before the completion at + * completion_index can be applied + */ +CINDEX_LINKAGE unsigned +clang_getCompletionNumFixIts(CXCodeCompleteResults *results, + unsigned completion_index); + +/** + * Fix-its that *must* be applied before inserting the text for the + * corresponding completion. + * + * By default, clang_codeCompleteAt() only returns completions with empty + * fix-its. Extra completions with non-empty fix-its should be explicitly + * requested by setting CXCodeComplete_IncludeCompletionsWithFixIts. + * + * For the clients to be able to compute position of the cursor after applying + * fix-its, the following conditions are guaranteed to hold for + * replacement_range of the stored fix-its: + * - Ranges in the fix-its are guaranteed to never contain the completion + * point (or identifier under completion point, if any) inside them, except + * at the start or at the end of the range. + * - If a fix-it range starts or ends with completion point (or starts or + * ends after the identifier under completion point), it will contain at + * least one character. It allows to unambiguously recompute completion + * point after applying the fix-it. + * + * The intuition is that provided fix-its change code around the identifier we + * complete, but are not allowed to touch the identifier itself or the + * completion point. One example of completions with corrections are the ones + * replacing '.' with '->' and vice versa: + * + * std::unique_ptr<std::vector<int>> vec_ptr; + * In 'vec_ptr.^', one of the completions is 'push_back', it requires + * replacing '.' with '->'. + * In 'vec_ptr->^', one of the completions is 'release', it requires + * replacing '->' with '.'. + * + * \param results The structure keeping all completion results + * + * \param completion_index The index of the completion + * + * \param fixit_index The index of the fix-it for the completion at + * completion_index + * + * \param replacement_range The fix-it range that must be replaced before the + * completion at completion_index can be applied + * + * \returns The fix-it string that must replace the code at replacement_range + * before the completion at completion_index can be applied + */ +CINDEX_LINKAGE CXString clang_getCompletionFixIt( + CXCodeCompleteResults *results, unsigned completion_index, + unsigned fixit_index, CXSourceRange *replacement_range); + +/** + * Flags that can be passed to \c clang_codeCompleteAt() to * modify its behavior. * * The enumerators in this enumeration can be bitwise-OR'd together to @@ -5136,163 +5335,176 @@ typedef struct { */ enum CXCodeComplete_Flags { /** - * \brief Whether to include macros within the set of code + * Whether to include macros within the set of code * completions returned. */ CXCodeComplete_IncludeMacros = 0x01, /** - * \brief Whether to include code patterns for language constructs + * Whether to include code patterns for language constructs * within the set of code completions, e.g., for loops. */ CXCodeComplete_IncludeCodePatterns = 0x02, /** - * \brief Whether to include brief documentation within the set of code + * Whether to include brief documentation within the set of code * completions returned. */ - CXCodeComplete_IncludeBriefComments = 0x04 + CXCodeComplete_IncludeBriefComments = 0x04, + + /** + * Whether to speed up completion by omitting top- or namespace-level entities + * defined in the preamble. There's no guarantee any particular entity is + * omitted. This may be useful if the headers are indexed externally. + */ + CXCodeComplete_SkipPreamble = 0x08, + + /** + * Whether to include completions with small + * fix-its, e.g. change '.' to '->' on member access, etc. + */ + CXCodeComplete_IncludeCompletionsWithFixIts = 0x10 }; /** - * \brief Bits that represent the context under which completion is occurring. + * Bits that represent the context under which completion is occurring. * * The enumerators in this enumeration may be bitwise-OR'd together if multiple * contexts are occurring simultaneously. */ enum CXCompletionContext { /** - * \brief The context for completions is unexposed, as only Clang results + * The context for completions is unexposed, as only Clang results * should be included. (This is equivalent to having no context bits set.) */ CXCompletionContext_Unexposed = 0, /** - * \brief Completions for any possible type should be included in the results. + * Completions for any possible type should be included in the results. */ CXCompletionContext_AnyType = 1 << 0, /** - * \brief Completions for any possible value (variables, function calls, etc.) + * Completions for any possible value (variables, function calls, etc.) * should be included in the results. */ CXCompletionContext_AnyValue = 1 << 1, /** - * \brief Completions for values that resolve to an Objective-C object should + * Completions for values that resolve to an Objective-C object should * be included in the results. */ CXCompletionContext_ObjCObjectValue = 1 << 2, /** - * \brief Completions for values that resolve to an Objective-C selector + * Completions for values that resolve to an Objective-C selector * should be included in the results. */ CXCompletionContext_ObjCSelectorValue = 1 << 3, /** - * \brief Completions for values that resolve to a C++ class type should be + * Completions for values that resolve to a C++ class type should be * included in the results. */ CXCompletionContext_CXXClassTypeValue = 1 << 4, /** - * \brief Completions for fields of the member being accessed using the dot + * Completions for fields of the member being accessed using the dot * operator should be included in the results. */ CXCompletionContext_DotMemberAccess = 1 << 5, /** - * \brief Completions for fields of the member being accessed using the arrow + * Completions for fields of the member being accessed using the arrow * operator should be included in the results. */ CXCompletionContext_ArrowMemberAccess = 1 << 6, /** - * \brief Completions for properties of the Objective-C object being accessed + * Completions for properties of the Objective-C object being accessed * using the dot operator should be included in the results. */ CXCompletionContext_ObjCPropertyAccess = 1 << 7, /** - * \brief Completions for enum tags should be included in the results. + * Completions for enum tags should be included in the results. */ CXCompletionContext_EnumTag = 1 << 8, /** - * \brief Completions for union tags should be included in the results. + * Completions for union tags should be included in the results. */ CXCompletionContext_UnionTag = 1 << 9, /** - * \brief Completions for struct tags should be included in the results. + * Completions for struct tags should be included in the results. */ CXCompletionContext_StructTag = 1 << 10, /** - * \brief Completions for C++ class names should be included in the results. + * Completions for C++ class names should be included in the results. */ CXCompletionContext_ClassTag = 1 << 11, /** - * \brief Completions for C++ namespaces and namespace aliases should be + * Completions for C++ namespaces and namespace aliases should be * included in the results. */ CXCompletionContext_Namespace = 1 << 12, /** - * \brief Completions for C++ nested name specifiers should be included in + * Completions for C++ nested name specifiers should be included in * the results. */ CXCompletionContext_NestedNameSpecifier = 1 << 13, /** - * \brief Completions for Objective-C interfaces (classes) should be included + * Completions for Objective-C interfaces (classes) should be included * in the results. */ CXCompletionContext_ObjCInterface = 1 << 14, /** - * \brief Completions for Objective-C protocols should be included in + * Completions for Objective-C protocols should be included in * the results. */ CXCompletionContext_ObjCProtocol = 1 << 15, /** - * \brief Completions for Objective-C categories should be included in + * Completions for Objective-C categories should be included in * the results. */ CXCompletionContext_ObjCCategory = 1 << 16, /** - * \brief Completions for Objective-C instance messages should be included + * Completions for Objective-C instance messages should be included * in the results. */ CXCompletionContext_ObjCInstanceMessage = 1 << 17, /** - * \brief Completions for Objective-C class messages should be included in + * Completions for Objective-C class messages should be included in * the results. */ CXCompletionContext_ObjCClassMessage = 1 << 18, /** - * \brief Completions for Objective-C selector names should be included in + * Completions for Objective-C selector names should be included in * the results. */ CXCompletionContext_ObjCSelectorName = 1 << 19, /** - * \brief Completions for preprocessor macro names should be included in + * Completions for preprocessor macro names should be included in * the results. */ CXCompletionContext_MacroName = 1 << 20, /** - * \brief Natural language completions should be included in the results. + * Natural language completions should be included in the results. */ CXCompletionContext_NaturalLanguage = 1 << 21, /** - * \brief The current context is unknown, so set all contexts. + * The current context is unknown, so set all contexts. */ CXCompletionContext_Unknown = ((1 << 22) - 1) }; /** - * \brief Returns a default set of code-completion options that can be + * Returns a default set of code-completion options that can be * passed to\c clang_codeCompleteAt(). */ CINDEX_LINKAGE unsigned clang_defaultCodeCompleteOptions(void); /** - * \brief Perform code completion at a given location in a translation unit. + * Perform code completion at a given location in a translation unit. * * This function performs code completion at a particular file, line, and * column within source code, providing results that suggest potential @@ -5309,7 +5521,7 @@ CINDEX_LINKAGE unsigned clang_defaultCodeCompleteOptions(void); * user types punctuation characters or whitespace, at which point the * code-completion location will coincide with the cursor. For example, if \c p * is a pointer, code-completion might be triggered after the "-" and then - * after the ">" in \c p->. When the code-completion location is afer the ">", + * after the ">" in \c p->. When the code-completion location is after the ">", * the completion results will provide, e.g., the members of the struct that * "p" points to. The client is responsible for placing the cursor at the * beginning of the token currently being typed, then filtering the results @@ -5369,7 +5581,7 @@ CXCodeCompleteResults *clang_codeCompleteAt(CXTranslationUnit TU, unsigned options); /** - * \brief Sort the code-completion results in case-insensitive alphabetical + * Sort the code-completion results in case-insensitive alphabetical * order. * * \param Results The set of results to sort. @@ -5380,20 +5592,20 @@ void clang_sortCodeCompletionResults(CXCompletionResult *Results, unsigned NumResults); /** - * \brief Free the given set of code-completion results. + * Free the given set of code-completion results. */ CINDEX_LINKAGE void clang_disposeCodeCompleteResults(CXCodeCompleteResults *Results); /** - * \brief Determine the number of diagnostics produced prior to the + * Determine the number of diagnostics produced prior to the * location where code completion was performed. */ CINDEX_LINKAGE unsigned clang_codeCompleteGetNumDiagnostics(CXCodeCompleteResults *Results); /** - * \brief Retrieve a diagnostic associated with the given code completion. + * Retrieve a diagnostic associated with the given code completion. * * \param Results the code completion results to query. * \param Index the zero-based diagnostic number to retrieve. @@ -5406,7 +5618,7 @@ CXDiagnostic clang_codeCompleteGetDiagnostic(CXCodeCompleteResults *Results, unsigned Index); /** - * \brief Determines what completions are appropriate for the context + * Determines what completions are appropriate for the context * the given code completion. * * \param Results the code completion results to query @@ -5419,7 +5631,7 @@ unsigned long long clang_codeCompleteGetContexts( CXCodeCompleteResults *Results); /** - * \brief Returns the cursor kind for the container for the current code + * Returns the cursor kind for the container for the current code * completion context. The container is only guaranteed to be set for * contexts where a container exists (i.e. member accesses or Objective-C * message sends); if there is not a container, this function will return @@ -5440,7 +5652,7 @@ enum CXCursorKind clang_codeCompleteGetContainerKind( unsigned *IsIncomplete); /** - * \brief Returns the USR for the container for the current code completion + * Returns the USR for the container for the current code completion * context. If there is not a container for the current context, this * function will return the empty string. * @@ -5452,7 +5664,7 @@ CINDEX_LINKAGE CXString clang_codeCompleteGetContainerUSR(CXCodeCompleteResults *Results); /** - * \brief Returns the currently-entered selector for an Objective-C message + * Returns the currently-entered selector for an Objective-C message * send, formatted like "initWithFoo:bar:". Only guaranteed to return a * non-empty string for CXCompletionContext_ObjCInstanceMessage and * CXCompletionContext_ObjCClassMessage. @@ -5476,13 +5688,13 @@ CXString clang_codeCompleteGetObjCSelector(CXCodeCompleteResults *Results); */ /** - * \brief Return a version string, suitable for showing to a user, but not + * Return a version string, suitable for showing to a user, but not * intended to be parsed (the format is not guaranteed to be stable). */ CINDEX_LINKAGE CXString clang_getClangVersion(void); /** - * \brief Enable/disable crash recovery. + * Enable/disable crash recovery. * * \param isEnabled Flag to indicate if crash recovery is enabled. A non-zero * value enables crash recovery, while 0 disables it. @@ -5490,7 +5702,7 @@ CINDEX_LINKAGE CXString clang_getClangVersion(void); CINDEX_LINKAGE void clang_toggleCrashRecovery(unsigned isEnabled); /** - * \brief Visitor invoked for each file in a translation unit + * Visitor invoked for each file in a translation unit * (used with clang_getInclusions()). * * This visitor function will be invoked by clang_getInclusions() for each @@ -5506,7 +5718,7 @@ typedef void (*CXInclusionVisitor)(CXFile included_file, CXClientData client_data); /** - * \brief Visit the set of preprocessor inclusions in a translation unit. + * Visit the set of preprocessor inclusions in a translation unit. * The visitor function is called with the provided data for every included * file. This does not include headers included by the PCH file (unless one * is inspecting the inclusions in the PCH file itself). @@ -5528,55 +5740,55 @@ typedef enum { } CXEvalResultKind ; /** - * \brief Evaluation result of a cursor + * Evaluation result of a cursor */ typedef void * CXEvalResult; /** - * \brief If cursor is a statement declaration tries to evaluate the + * If cursor is a statement declaration tries to evaluate the * statement and if its variable, tries to evaluate its initializer, * into its corresponding type. */ CINDEX_LINKAGE CXEvalResult clang_Cursor_Evaluate(CXCursor C); /** - * \brief Returns the kind of the evaluated result. + * Returns the kind of the evaluated result. */ CINDEX_LINKAGE CXEvalResultKind clang_EvalResult_getKind(CXEvalResult E); /** - * \brief Returns the evaluation result as integer if the + * Returns the evaluation result as integer if the * kind is Int. */ CINDEX_LINKAGE int clang_EvalResult_getAsInt(CXEvalResult E); /** - * \brief Returns the evaluation result as a long long integer if the + * Returns the evaluation result as a long long integer if the * kind is Int. This prevents overflows that may happen if the result is * returned with clang_EvalResult_getAsInt. */ CINDEX_LINKAGE long long clang_EvalResult_getAsLongLong(CXEvalResult E); /** - * \brief Returns a non-zero value if the kind is Int and the evaluation + * Returns a non-zero value if the kind is Int and the evaluation * result resulted in an unsigned integer. */ CINDEX_LINKAGE unsigned clang_EvalResult_isUnsignedInt(CXEvalResult E); /** - * \brief Returns the evaluation result as an unsigned integer if + * Returns the evaluation result as an unsigned integer if * the kind is Int and clang_EvalResult_isUnsignedInt is non-zero. */ CINDEX_LINKAGE unsigned long long clang_EvalResult_getAsUnsigned(CXEvalResult E); /** - * \brief Returns the evaluation result as double if the + * Returns the evaluation result as double if the * kind is double. */ CINDEX_LINKAGE double clang_EvalResult_getAsDouble(CXEvalResult E); /** - * \brief Returns the evaluation result as a constant string if the + * Returns the evaluation result as a constant string if the * kind is other than Int or float. User must not free this pointer, * instead call clang_EvalResult_dispose on the CXEvalResult returned * by clang_Cursor_Evaluate. @@ -5584,7 +5796,7 @@ CINDEX_LINKAGE double clang_EvalResult_getAsDouble(CXEvalResult E); CINDEX_LINKAGE const char* clang_EvalResult_getAsStr(CXEvalResult E); /** - * \brief Disposes the created Eval memory. + * Disposes the created Eval memory. */ CINDEX_LINKAGE void clang_EvalResult_dispose(CXEvalResult E); /** @@ -5597,12 +5809,12 @@ CINDEX_LINKAGE void clang_EvalResult_dispose(CXEvalResult E); */ /** - * \brief A remapping of original source files and their translated files. + * A remapping of original source files and their translated files. */ typedef void *CXRemapping; /** - * \brief Retrieve a remapping. + * Retrieve a remapping. * * \param path the path that contains metadata about remappings. * @@ -5612,7 +5824,7 @@ typedef void *CXRemapping; CINDEX_LINKAGE CXRemapping clang_getRemappings(const char *path); /** - * \brief Retrieve a remapping. + * Retrieve a remapping. * * \param filePaths pointer to an array of file paths containing remapping info. * @@ -5626,12 +5838,12 @@ CXRemapping clang_getRemappingsFromFileList(const char **filePaths, unsigned numFiles); /** - * \brief Determine the number of remappings. + * Determine the number of remappings. */ CINDEX_LINKAGE unsigned clang_remap_getNumFiles(CXRemapping); /** - * \brief Get the original and the associated filename from the remapping. + * Get the original and the associated filename from the remapping. * * \param original If non-NULL, will be set to the original filename. * @@ -5642,7 +5854,7 @@ CINDEX_LINKAGE void clang_remap_getFilenames(CXRemapping, unsigned index, CXString *original, CXString *transformed); /** - * \brief Dispose the remapping. + * Dispose the remapping. */ CINDEX_LINKAGE void clang_remap_dispose(CXRemapping); @@ -5667,15 +5879,15 @@ typedef struct CXCursorAndRangeVisitor { typedef enum { /** - * \brief Function returned successfully. + * Function returned successfully. */ CXResult_Success = 0, /** - * \brief One of the parameters was invalid for the function. + * One of the parameters was invalid for the function. */ CXResult_Invalid = 1, /** - * \brief The function was terminated by a callback (e.g. it returned + * The function was terminated by a callback (e.g. it returned * CXVisit_Break) */ CXResult_VisitBreak = 2 @@ -5683,7 +5895,7 @@ typedef enum { } CXResult; /** - * \brief Find references of a declaration in a specific file. + * Find references of a declaration in a specific file. * * \param cursor pointing to a declaration or a reference of one. * @@ -5700,7 +5912,7 @@ CINDEX_LINKAGE CXResult clang_findReferencesInFile(CXCursor cursor, CXFile file, CXCursorAndRangeVisitor visitor); /** - * \brief Find #import/#include directives in a specific file. + * Find #import/#include directives in a specific file. * * \param TU translation unit containing the file to query. * @@ -5733,29 +5945,29 @@ CXResult clang_findIncludesInFileWithBlock(CXTranslationUnit, CXFile, #endif /** - * \brief The client's data object that is associated with a CXFile. + * The client's data object that is associated with a CXFile. */ typedef void *CXIdxClientFile; /** - * \brief The client's data object that is associated with a semantic entity. + * The client's data object that is associated with a semantic entity. */ typedef void *CXIdxClientEntity; /** - * \brief The client's data object that is associated with a semantic container + * The client's data object that is associated with a semantic container * of entities. */ typedef void *CXIdxClientContainer; /** - * \brief The client's data object that is associated with an AST file (PCH + * The client's data object that is associated with an AST file (PCH * or module). */ typedef void *CXIdxClientASTFile; /** - * \brief Source location passed to index callbacks. + * Source location passed to index callbacks. */ typedef struct { void *ptr_data[2]; @@ -5763,48 +5975,48 @@ typedef struct { } CXIdxLoc; /** - * \brief Data for ppIncludedFile callback. + * Data for ppIncludedFile callback. */ typedef struct { /** - * \brief Location of '#' in the \#include/\#import directive. + * Location of '#' in the \#include/\#import directive. */ CXIdxLoc hashLoc; /** - * \brief Filename as written in the \#include/\#import directive. + * Filename as written in the \#include/\#import directive. */ const char *filename; /** - * \brief The actual file that the \#include/\#import directive resolved to. + * The actual file that the \#include/\#import directive resolved to. */ CXFile file; int isImport; int isAngled; /** - * \brief Non-zero if the directive was automatically turned into a module + * Non-zero if the directive was automatically turned into a module * import. */ int isModuleImport; } CXIdxIncludedFileInfo; /** - * \brief Data for IndexerCallbacks#importedASTFile. + * Data for IndexerCallbacks#importedASTFile. */ typedef struct { /** - * \brief Top level AST file containing the imported PCH, module or submodule. + * Top level AST file containing the imported PCH, module or submodule. */ CXFile file; /** - * \brief The imported module or NULL if the AST file is a PCH. + * The imported module or NULL if the AST file is a PCH. */ CXModule module; /** - * \brief Location where the file is imported. Applicable only for modules. + * Location where the file is imported. Applicable only for modules. */ CXIdxLoc loc; /** - * \brief Non-zero if an inclusion directive was automatically turned into + * Non-zero if an inclusion directive was automatically turned into * a module import. Applicable only for modules. */ int isImplicit; @@ -5855,7 +6067,7 @@ typedef enum { } CXIdxEntityLanguage; /** - * \brief Extra C++ template information for an entity. This can apply to: + * Extra C++ template information for an entity. This can apply to: * CXIdxEntity_Function * CXIdxEntity_CXXClass * CXIdxEntity_CXXStaticMethod @@ -5916,7 +6128,7 @@ typedef struct { CXIdxLoc loc; const CXIdxContainerInfo *semanticContainer; /** - * \brief Generally same as #semanticContainer but can be different in + * Generally same as #semanticContainer but can be different in * cases like out-of-line C++ member functions. */ const CXIdxContainerInfo *lexicalContainer; @@ -5925,7 +6137,7 @@ typedef struct { int isContainer; const CXIdxContainerInfo *declAsContainer; /** - * \brief Whether the declaration exists in code or was created implicitly + * Whether the declaration exists in code or was created implicitly * by the compiler, e.g. implicit Objective-C methods for properties. */ int isImplicit; @@ -5991,36 +6203,58 @@ typedef struct { } CXIdxCXXClassDeclInfo; /** - * \brief Data for IndexerCallbacks#indexEntityReference. + * Data for IndexerCallbacks#indexEntityReference. + * + * This may be deprecated in a future version as this duplicates + * the \c CXSymbolRole_Implicit bit in \c CXSymbolRole. */ typedef enum { /** - * \brief The entity is referenced directly in user's code. + * The entity is referenced directly in user's code. */ CXIdxEntityRef_Direct = 1, /** - * \brief An implicit reference, e.g. a reference of an Objective-C method + * An implicit reference, e.g. a reference of an Objective-C method * via the dot syntax. */ CXIdxEntityRef_Implicit = 2 } CXIdxEntityRefKind; /** - * \brief Data for IndexerCallbacks#indexEntityReference. + * Roles that are attributed to symbol occurrences. + * + * Internal: this currently mirrors low 9 bits of clang::index::SymbolRole with + * higher bits zeroed. These high bits may be exposed in the future. + */ +typedef enum { + CXSymbolRole_None = 0, + CXSymbolRole_Declaration = 1 << 0, + CXSymbolRole_Definition = 1 << 1, + CXSymbolRole_Reference = 1 << 2, + CXSymbolRole_Read = 1 << 3, + CXSymbolRole_Write = 1 << 4, + CXSymbolRole_Call = 1 << 5, + CXSymbolRole_Dynamic = 1 << 6, + CXSymbolRole_AddressOf = 1 << 7, + CXSymbolRole_Implicit = 1 << 8 +} CXSymbolRole; + +/** + * Data for IndexerCallbacks#indexEntityReference. */ typedef struct { CXIdxEntityRefKind kind; /** - * \brief Reference cursor. + * Reference cursor. */ CXCursor cursor; CXIdxLoc loc; /** - * \brief The entity that gets referenced. + * The entity that gets referenced. */ const CXIdxEntityInfo *referencedEntity; /** - * \brief Immediate "parent" of the reference. For example: + * Immediate "parent" of the reference. For example: * * \code * Foo *var; @@ -6032,24 +6266,28 @@ typedef struct { */ const CXIdxEntityInfo *parentEntity; /** - * \brief Lexical container context of the reference. + * Lexical container context of the reference. */ const CXIdxContainerInfo *container; + /** + * Sets of symbol roles of the reference. + */ + CXSymbolRole role; } CXIdxEntityRefInfo; /** - * \brief A group of callbacks used by #clang_indexSourceFile and + * A group of callbacks used by #clang_indexSourceFile and * #clang_indexTranslationUnit. */ typedef struct { /** - * \brief Called periodically to check whether indexing should be aborted. + * Called periodically to check whether indexing should be aborted. * Should return 0 to continue, and non-zero to abort. */ int (*abortQuery)(CXClientData client_data, void *reserved); /** - * \brief Called at the end of indexing; passes the complete diagnostic set. + * Called at the end of indexing; passes the complete diagnostic set. */ void (*diagnostic)(CXClientData client_data, CXDiagnosticSet, void *reserved); @@ -6058,13 +6296,13 @@ typedef struct { CXFile mainFile, void *reserved); /** - * \brief Called when a file gets \#included/\#imported. + * Called when a file gets \#included/\#imported. */ CXIdxClientFile (*ppIncludedFile)(CXClientData client_data, const CXIdxIncludedFileInfo *); /** - * \brief Called when a AST file (PCH or module) gets imported. + * Called when a AST file (PCH or module) gets imported. * * AST files will not get indexed (there will not be callbacks to index all * the entities in an AST file). The recommended action is that, if the AST @@ -6075,7 +6313,7 @@ typedef struct { const CXIdxImportedASTFileInfo *); /** - * \brief Called at the beginning of indexing a translation unit. + * Called at the beginning of indexing a translation unit. */ CXIdxClientContainer (*startedTranslationUnit)(CXClientData client_data, void *reserved); @@ -6084,7 +6322,7 @@ typedef struct { const CXIdxDeclInfo *); /** - * \brief Called to index a reference of an entity. + * Called to index a reference of an entity. */ void (*indexEntityReference)(CXClientData client_data, const CXIdxEntityRefInfo *); @@ -6115,39 +6353,39 @@ CINDEX_LINKAGE const CXIdxCXXClassDeclInfo * clang_index_getCXXClassDeclInfo(const CXIdxDeclInfo *); /** - * \brief For retrieving a custom CXIdxClientContainer attached to a + * For retrieving a custom CXIdxClientContainer attached to a * container. */ CINDEX_LINKAGE CXIdxClientContainer clang_index_getClientContainer(const CXIdxContainerInfo *); /** - * \brief For setting a custom CXIdxClientContainer attached to a + * For setting a custom CXIdxClientContainer attached to a * container. */ CINDEX_LINKAGE void clang_index_setClientContainer(const CXIdxContainerInfo *,CXIdxClientContainer); /** - * \brief For retrieving a custom CXIdxClientEntity attached to an entity. + * For retrieving a custom CXIdxClientEntity attached to an entity. */ CINDEX_LINKAGE CXIdxClientEntity clang_index_getClientEntity(const CXIdxEntityInfo *); /** - * \brief For setting a custom CXIdxClientEntity attached to an entity. + * For setting a custom CXIdxClientEntity attached to an entity. */ CINDEX_LINKAGE void clang_index_setClientEntity(const CXIdxEntityInfo *, CXIdxClientEntity); /** - * \brief An indexing action/session, to be applied to one or multiple + * An indexing action/session, to be applied to one or multiple * translation units. */ typedef void *CXIndexAction; /** - * \brief An indexing action/session, to be applied to one or multiple + * An indexing action/session, to be applied to one or multiple * translation units. * * \param CIdx The index object with which the index action will be associated. @@ -6155,7 +6393,7 @@ typedef void *CXIndexAction; CINDEX_LINKAGE CXIndexAction clang_IndexAction_create(CXIndex CIdx); /** - * \brief Destroy the given index action. + * Destroy the given index action. * * The index action must not be destroyed until all of the translation units * created within that index action have been destroyed. @@ -6164,36 +6402,36 @@ CINDEX_LINKAGE void clang_IndexAction_dispose(CXIndexAction); typedef enum { /** - * \brief Used to indicate that no special indexing options are needed. + * Used to indicate that no special indexing options are needed. */ CXIndexOpt_None = 0x0, /** - * \brief Used to indicate that IndexerCallbacks#indexEntityReference should + * Used to indicate that IndexerCallbacks#indexEntityReference should * be invoked for only one reference of an entity per source file that does * not also include a declaration/definition of the entity. */ CXIndexOpt_SuppressRedundantRefs = 0x1, /** - * \brief Function-local symbols should be indexed. If this is not set + * Function-local symbols should be indexed. If this is not set * function-local symbols will be ignored. */ CXIndexOpt_IndexFunctionLocalSymbols = 0x2, /** - * \brief Implicit function/class template instantiations should be indexed. + * Implicit function/class template instantiations should be indexed. * If this is not set, implicit instantiations will be ignored. */ CXIndexOpt_IndexImplicitTemplateInstantiations = 0x4, /** - * \brief Suppress all compiler warnings when parsing for indexing. + * Suppress all compiler warnings when parsing for indexing. */ CXIndexOpt_SuppressWarnings = 0x8, /** - * \brief Skip a function/method body that was already parsed during an + * Skip a function/method body that was already parsed during an * indexing session associated with a \c CXIndexAction object. * Bodies in system headers are always skipped. */ @@ -6202,7 +6440,7 @@ typedef enum { } CXIndexOptFlags; /** - * \brief Index the given source file and the translation unit corresponding + * Index the given source file and the translation unit corresponding * to that file via callbacks implemented through #IndexerCallbacks. * * \param client_data pointer data supplied by the client, which will @@ -6240,7 +6478,7 @@ CINDEX_LINKAGE int clang_indexSourceFile(CXIndexAction, unsigned TU_options); /** - * \brief Same as clang_indexSourceFile but requires a full command line + * Same as clang_indexSourceFile but requires a full command line * for \c command_line_args including argv[0]. This is useful if the standard * library paths are relative to the binary. */ @@ -6252,7 +6490,7 @@ CINDEX_LINKAGE int clang_indexSourceFileFullArgv( unsigned num_unsaved_files, CXTranslationUnit *out_TU, unsigned TU_options); /** - * \brief Index the given translation unit via callbacks implemented through + * Index the given translation unit via callbacks implemented through * #IndexerCallbacks. * * The order of callback invocations is not guaranteed to be the same as @@ -6275,7 +6513,7 @@ CINDEX_LINKAGE int clang_indexTranslationUnit(CXIndexAction, CXTranslationUnit); /** - * \brief Retrieve the CXIdxFile, file, line, column, and offset represented by + * Retrieve the CXIdxFile, file, line, column, and offset represented by * the given CXIdxLoc. * * If the location refers into a macro expansion, retrieves the @@ -6290,13 +6528,13 @@ CINDEX_LINKAGE void clang_indexLoc_getFileLocation(CXIdxLoc loc, unsigned *offset); /** - * \brief Retrieve the CXSourceLocation represented by the given CXIdxLoc. + * Retrieve the CXSourceLocation represented by the given CXIdxLoc. */ CINDEX_LINKAGE CXSourceLocation clang_indexLoc_getCXSourceLocation(CXIdxLoc loc); /** - * \brief Visitor invoked for each field found by a traversal. + * Visitor invoked for each field found by a traversal. * * This visitor function will be invoked for each field found by * \c clang_Type_visitFields. Its first argument is the cursor being @@ -6310,7 +6548,7 @@ typedef enum CXVisitorResult (*CXFieldVisitor)(CXCursor C, CXClientData client_data); /** - * \brief Visit the fields of a particular type. + * Visit the fields of a particular type. * * This function visits all the direct fields of the given cursor, * invoking the given \p visitor function with the cursors of each |