From c7a646fc01606f99d5208e89b80149001cdbc068 Mon Sep 17 00:00:00 2001 From: James Dennett Date: Mon, 2 Jul 2012 23:17:34 +0000 Subject: [PATCH] Documentation cleanup: * Primarily, added \brief to most of include/clang/Basic, instead of prefixing the comments with "DeclaredName - "; * Made some brief summaries significantly briefer; * Fixed up some erroneous uses of \see and \arg; * Fixed up some extraneous backslashes in \code...\endcode blocks; * Fixed up some typos/spelling errors. llvm-svn: 159616 --- clang/include/clang/Basic/ABI.h | 34 +-- clang/include/clang/Basic/AddressSpaces.h | 7 +- clang/include/clang/Basic/AttrKinds.h | 2 +- clang/include/clang/Basic/Builtins.h | 26 +- clang/include/clang/Basic/Diagnostic.h | 266 ++++++++++-------- clang/include/clang/Basic/DiagnosticIDs.h | 72 ++--- clang/include/clang/Basic/FileManager.h | 54 ++-- .../include/clang/Basic/FileSystemStatCache.h | 7 +- clang/include/clang/Basic/IdentifierTable.h | 56 ++-- clang/include/clang/Basic/Lambda.h | 7 +- clang/include/clang/Basic/LangOptions.h | 13 +- clang/include/clang/Basic/Linkage.h | 13 +- clang/include/clang/Basic/ObjCRuntime.h | 34 ++- clang/include/clang/Basic/OpenCL.h | 2 +- clang/include/clang/Basic/OperatorKinds.h | 4 +- clang/include/clang/Basic/PartialDiagnostic.h | 28 +- clang/include/clang/Basic/PrettyStackTrace.h | 4 +- clang/include/clang/Basic/SourceLocation.h | 49 ++-- clang/include/clang/Basic/SourceManager.h | 74 ++--- .../clang/Basic/SourceManagerInternals.h | 28 +- clang/include/clang/Basic/Specifiers.h | 36 ++- clang/include/clang/Basic/TargetBuiltins.h | 18 +- clang/include/clang/Basic/TargetInfo.h | 234 ++++++++------- clang/include/clang/Basic/TargetOptions.h | 2 +- clang/include/clang/Basic/TokenKinds.h | 14 +- clang/include/clang/Basic/TypeTraits.h | 8 +- clang/include/clang/Basic/Version.h | 29 +- clang/include/clang/Basic/VersionTuple.h | 33 ++- clang/include/clang/Basic/Visibility.h | 10 +- 29 files changed, 633 insertions(+), 531 deletions(-) diff --git a/clang/include/clang/Basic/ABI.h b/clang/include/clang/Basic/ABI.h index 9599abe77a5a..fecf613a0461 100644 --- a/clang/include/clang/Basic/ABI.h +++ b/clang/include/clang/Basic/ABI.h @@ -20,27 +20,27 @@ namespace clang { -/// CXXCtorType - C++ constructor types +/// \brief C++ constructor types. enum CXXCtorType { - Ctor_Complete, // Complete object ctor - Ctor_Base, // Base object ctor - Ctor_CompleteAllocating // Complete object allocating ctor + Ctor_Complete, ///< Complete object ctor + Ctor_Base, ///< Base object ctor + Ctor_CompleteAllocating ///< Complete object allocating ctor }; -/// CXXDtorType - C++ destructor types +/// \brief C++ destructor types. enum CXXDtorType { - Dtor_Deleting, // Deleting dtor - Dtor_Complete, // Complete object dtor - Dtor_Base // Base object dtor + Dtor_Deleting, ///< Deleting dtor + Dtor_Complete, ///< Complete object dtor + Dtor_Base ///< Base object dtor }; -/// ReturnAdjustment - A return adjustment. +/// \brief A return adjustment. struct ReturnAdjustment { - /// NonVirtual - The non-virtual adjustment from the derived object to its + /// \brief The non-virtual adjustment from the derived object to its /// nearest virtual base. int64_t NonVirtual; - /// VBaseOffsetOffset - The offset (in bytes), relative to the address point + /// \brief The offset (in bytes), relative to the address point /// of the virtual base class offset. int64_t VBaseOffsetOffset; @@ -64,13 +64,13 @@ struct ReturnAdjustment { } }; -/// ThisAdjustment - A 'this' pointer adjustment. +/// \brief A \c this pointer adjustment. struct ThisAdjustment { - /// NonVirtual - The non-virtual adjustment from the derived object to its + /// \brief The non-virtual adjustment from the derived object to its /// nearest virtual base. int64_t NonVirtual; - /// VCallOffsetOffset - The offset (in bytes), relative to the address point, + /// \brief The offset (in bytes), relative to the address point, /// of the virtual call offset. int64_t VCallOffsetOffset; @@ -94,13 +94,13 @@ struct ThisAdjustment { } }; -/// ThunkInfo - The 'this' pointer adjustment as well as an optional return +/// \brief The \c this pointer adjustment as well as an optional return /// adjustment for a thunk. struct ThunkInfo { - /// This - The 'this' pointer adjustment. + /// \brief The \c this pointer adjustment. ThisAdjustment This; - /// Return - The return adjustment. + /// \brief The return adjustment. ReturnAdjustment Return; ThunkInfo() { } diff --git a/clang/include/clang/Basic/AddressSpaces.h b/clang/include/clang/Basic/AddressSpaces.h index b8077ec15102..4b1cea50f884 100644 --- a/clang/include/clang/Basic/AddressSpaces.h +++ b/clang/include/clang/Basic/AddressSpaces.h @@ -9,7 +9,7 @@ /// /// \file /// \brief Provides definitions for the various language-specific address -/// spaces. +/// spaces. /// //===----------------------------------------------------------------------===// @@ -20,8 +20,9 @@ namespace clang { namespace LangAS { -/// This enum defines the set of possible language-specific address spaces. -/// It uses a high starting offset so as not to conflict with any address +/// \brief Defines the set of possible language-specific address spaces. +/// +/// This uses a high starting offset so as not to conflict with any address /// space used by a target. enum ID { Offset = 0xFFFF00, diff --git a/clang/include/clang/Basic/AttrKinds.h b/clang/include/clang/Basic/AttrKinds.h index a429336e0603..150a30e73d3f 100644 --- a/clang/include/clang/Basic/AttrKinds.h +++ b/clang/include/clang/Basic/AttrKinds.h @@ -19,7 +19,7 @@ namespace clang { namespace attr { -// Kind - This is a list of all the recognized kinds of attributes. +// \brief A list of all the recognized kinds of attributes. enum Kind { #define ATTR(X) X, #define LAST_INHERITABLE_ATTR(X) X, LAST_INHERITABLE = X, diff --git a/clang/include/clang/Basic/Builtins.h b/clang/include/clang/Basic/Builtins.h index aa6f9f9355f9..257daf10ecee 100644 --- a/clang/include/clang/Basic/Builtins.h +++ b/clang/include/clang/Basic/Builtins.h @@ -57,7 +57,7 @@ struct Info { bool operator!=(const Info &RHS) const { return !(*this == RHS); } }; -/// Builtin::Context - This holds information about target-independent and +/// \brief Holds information about both target-independent and /// target-specific builtins, allowing easy queries by clients. class Context { const Info *TSRecords; @@ -68,7 +68,7 @@ public: /// \brief Perform target-specific initialization void InitializeTarget(const TargetInfo &Target); - /// InitializeBuiltins - Mark the identifiers for all the builtins with their + /// \brief Mark the identifiers for all the builtins with their /// appropriate builtin ID # and mark any non-portable builtin identifiers as /// such. void InitializeBuiltins(IdentifierTable &Table, const LangOptions& LangOpts); @@ -77,39 +77,39 @@ public: void GetBuiltinNames(SmallVectorImpl &Names, bool NoBuiltins); - /// Builtin::GetName - Return the identifier name for the specified builtin, + /// \brief Return the identifier name for the specified builtin, /// e.g. "__builtin_abs". const char *GetName(unsigned ID) const { return GetRecord(ID).Name; } - /// GetTypeString - Get the type descriptor string for the specified builtin. + /// \brief Get the type descriptor string for the specified builtin. const char *GetTypeString(unsigned ID) const { return GetRecord(ID).Type; } - /// isConst - Return true if this function has no side effects and doesn't + /// \brief Return true if this function has no side effects and doesn't /// read memory. bool isConst(unsigned ID) const { return strchr(GetRecord(ID).Attributes, 'c') != 0; } - /// isNoThrow - Return true if we know this builtin never throws an exception. + /// \brief Return true if we know this builtin never throws an exception. bool isNoThrow(unsigned ID) const { return strchr(GetRecord(ID).Attributes, 'n') != 0; } - /// isNoReturn - Return true if we know this builtin never returns. + /// \brief Return true if we know this builtin never returns. bool isNoReturn(unsigned ID) const { return strchr(GetRecord(ID).Attributes, 'r') != 0; } - /// isReturnsTwice - Return true if we know this builtin can return twice. + /// \brief Return true if we know this builtin can return twice. bool isReturnsTwice(unsigned ID) const { return strchr(GetRecord(ID).Attributes, 'j') != 0; } - /// isLibFunction - Return true if this is a builtin for a libc/libm function, + /// \brief Return true if this is a builtin for a libc/libm function, /// with a "__builtin_" prefix (e.g. __builtin_abs). bool isLibFunction(unsigned ID) const { return strchr(GetRecord(ID).Attributes, 'F') != 0; @@ -147,10 +147,10 @@ public: /// argument and whether this function as a va_list argument. bool isScanfLike(unsigned ID, unsigned &FormatIdx, bool &HasVAListArg); - /// isConstWithoutErrno - Return true if this function has no side - /// effects and doesn't read memory, except for possibly errno. Such - /// functions can be const when the MathErrno lang option is - /// disabled. + /// \brief Return true if this function has no side effects and doesn't + /// read memory, except for possibly errno. + /// + /// Such functions can be const when the MathErrno lang option is disabled. bool isConstWithoutErrno(unsigned ID) const { return strchr(GetRecord(ID).Attributes, 'e') != 0; } diff --git a/clang/include/clang/Basic/Diagnostic.h b/clang/include/clang/Basic/Diagnostic.h index 361093b9d83f..e46bbb6d1b4f 100644 --- a/clang/include/clang/Basic/Diagnostic.h +++ b/clang/include/clang/Basic/Diagnostic.h @@ -83,7 +83,7 @@ public: } /// \brief Create a code modification hint that inserts the given - /// code from \arg FromRange at a specific location. + /// code from \p FromRange at a specific location. static FixItHint CreateInsertionFromRange(SourceLocation InsertionLoc, CharSourceRange FromRange, bool BeforePreviousInsertions = false) { @@ -122,14 +122,15 @@ public: } }; -/// DiagnosticsEngine - This concrete class is used by the front-end to report -/// problems and issues. It massages the diagnostics (e.g. handling things like -/// "report warnings as errors" and passes them off to the DiagnosticConsumer -/// for reporting to the user. DiagnosticsEngine is tied to one translation unit -/// and one SourceManager. +/// \brief Concrete class used by the front-end to report problems and issues. +/// +/// This massages the diagnostics (e.g. handling things like "report warnings +/// as errors" and passes them off to the DiagnosticConsumer for reporting to +/// the user. DiagnosticsEngine is tied to one translation unit and one +/// SourceManager. class DiagnosticsEngine : public RefCountedBase { public: - /// Level - The level of the diagnostic, after it has been through mapping. + /// \brief The level of the diagnostic, after it has been through mapping. enum Level { Ignored = DiagnosticIDs::Ignored, Note = DiagnosticIDs::Note, @@ -138,35 +139,36 @@ public: Fatal = DiagnosticIDs::Fatal }; - /// ExtensionHandling - How do we handle otherwise-unmapped extension? This - /// is controlled by -pedantic and -pedantic-errors. + /// \brief How do we handle otherwise-unmapped extension? + /// + /// This is controlled by -pedantic and -pedantic-errors. enum ExtensionHandling { Ext_Ignore, Ext_Warn, Ext_Error }; enum ArgumentKind { - ak_std_string, // std::string - ak_c_string, // const char * - ak_sint, // int - ak_uint, // unsigned - ak_identifierinfo, // IdentifierInfo - ak_qualtype, // QualType - ak_declarationname, // DeclarationName - ak_nameddecl, // NamedDecl * - ak_nestednamespec, // NestedNameSpecifier * - ak_declcontext, // DeclContext * - ak_qualtype_pair // pair + ak_std_string, ///< std::string + ak_c_string, ///< const char * + ak_sint, ///< int + ak_uint, ///< unsigned + ak_identifierinfo, ///< IdentifierInfo + ak_qualtype, ///< QualType + ak_declarationname, ///< DeclarationName + ak_nameddecl, ///< NamedDecl * + ak_nestednamespec, ///< NestedNameSpecifier * + ak_declcontext, ///< DeclContext * + ak_qualtype_pair ///< pair }; - /// Specifies which overload candidates to display when overload resolution - /// fails. + /// \brief Specifies which overload candidates to display when overload + /// resolution fails. enum OverloadsShown { Ovl_All, ///< Show all overloads. Ovl_Best ///< Show just the "best" overload candidates. }; - /// ArgumentValue - This typedef represents on argument value, which is a - /// union discriminated by ArgumentKind, with a value. + /// \brief Represents on argument value, which is a union discriminated + /// by ArgumentKind, with a value. typedef std::pair ArgumentValue; private: @@ -192,12 +194,13 @@ private: bool OwnsDiagClient; SourceManager *SourceMgr; - /// \brief Mapping information for diagnostics. Mapping info is - /// packed into four bits per diagnostic. The low three bits are the mapping - /// (an instance of diag::Mapping), or zero if unset. The high bit is set - /// when the mapping was established as a user mapping. If the high bit is - /// clear, then the low bits are set to the default value, and should be - /// mapped with -pedantic, -Werror, etc. + /// \brief Mapping information for diagnostics. + /// + /// Mapping info is packed into four bits per diagnostic. The low three + /// bits are the mapping (an instance of diag::Mapping), or zero if unset. + /// The high bit is set when the mapping was established as a user mapping. + /// If the high bit is clear, then the low bits are set to the default + /// value, and should be mapped with -pedantic, -Werror, etc. /// /// A new DiagState is created and kept around when diagnostic pragmas modify /// the state so that we know what is the diagnostic state at any given @@ -225,8 +228,10 @@ private: std::list DiagStates; /// \brief Represents a point in source where the diagnostic state was - /// modified because of a pragma. 'Loc' can be null if the point represents - /// the diagnostic state modifications done through the command-line. + /// modified because of a pragma. + /// + /// 'Loc' can be null if the point represents the diagnostic state + /// modifications done through the command-line. struct DiagStatePoint { DiagState *State; FullSourceLoc Loc; @@ -244,9 +249,11 @@ private: } }; - /// \brief A vector of all DiagStatePoints representing changes in diagnostic - /// state due to diagnostic pragmas. The vector is always sorted according to - /// the SourceLocation of the DiagStatePoint. + /// \brief A sorted vector of all DiagStatePoints representing changes in + /// diagnostic state due to diagnostic pragmas. + /// + /// The vector is always sorted according to the SourceLocation of the + /// DiagStatePoint. typedef std::vector DiagStatePointsTy; mutable DiagStatePointsTy DiagStatePoints; @@ -276,9 +283,10 @@ private: /// the given source location. DiagStatePointsTy::iterator GetDiagStatePointForLoc(SourceLocation Loc) const; - /// ErrorOccurred / FatalErrorOccurred - This is set to true when an error or - /// fatal error is emitted, and is sticky. + /// \brief Sticky flag set to \c true when an error is emitted. bool ErrorOccurred; + + /// \brief Sticky flag set to \c true when a fatal error is emitted. bool FatalErrorOccurred; /// \brief Indicates that an unrecoverable error has occurred. @@ -289,18 +297,20 @@ private: unsigned TrapNumErrorsOccurred; unsigned TrapNumUnrecoverableErrorsOccurred; - /// LastDiagLevel - This is the level of the last diagnostic emitted. This is - /// used to emit continuation diagnostics with the same level as the + /// \brief The level of the last diagnostic emitted. + /// + /// This is used to emit continuation diagnostics with the same level as the /// diagnostic that they follow. DiagnosticIDs::Level LastDiagLevel; - unsigned NumWarnings; // Number of warnings reported - unsigned NumErrors; // Number of errors reported - unsigned NumErrorsSuppressed; // Number of errors suppressed + unsigned NumWarnings; ///< Number of warnings reported + unsigned NumErrors; ///< Number of errors reported + unsigned NumErrorsSuppressed; ///< Number of errors suppressed - /// ArgToStringFn - A function pointer that converts an opaque diagnostic - /// argument to a strings. This takes the modifiers and argument that was - /// present in the diagnostic. + /// \brief A function pointer that converts an opaque diagnostic + /// argument to a strings. + /// + /// This takes the modifiers and argument that was present in the diagnostic. /// /// The PrevArgs array (whose length is NumPrevArgs) indicates the previous /// arguments formatted for this diagnostic. Implementations of this function @@ -366,14 +376,15 @@ public: // how diagnostics are emitted. // - /// pushMappings - Copies the current DiagMappings and pushes the new copy + /// \brief Copies the current DiagMappings and pushes the new copy /// onto the top of the stack. void pushMappings(SourceLocation Loc); - /// popMappings - Pops the current DiagMappings off the top of the stack - /// causing the new top of the stack to be the active mappings. Returns - /// true if the pop happens, false if there is only one DiagMapping on the - /// stack. + /// \brief Pops the current DiagMappings off the top of the stack, + /// causing the new top of the stack to be the active mappings. + /// + /// \returns \c true if the pop happens, \c false if there is only one + /// DiagMapping on the stack. bool popMappings(SourceLocation Loc); /// \brief Set the diagnostic client associated with this diagnostic object. @@ -382,8 +393,10 @@ public: /// ownership of \c client. void setClient(DiagnosticConsumer *client, bool ShouldOwnClient = true); - /// setErrorLimit - Specify a limit for the number of errors we should - /// emit before giving up. Zero disables the limit. + /// \brief Specify a limit for the number of errors we should + /// emit before giving up. + /// + /// Zero disables the limit. void setErrorLimit(unsigned Limit) { ErrorLimit = Limit; } /// \brief Specify the maximum number of template instantiation @@ -410,29 +423,28 @@ public: return ConstexprBacktraceLimit; } - /// setIgnoreAllWarnings - When set to true, any unmapped warnings are - /// ignored. If this and WarningsAsErrors are both set, then this one wins. + /// \brief When set to true, any unmapped warnings are ignored. + /// + /// If this and WarningsAsErrors are both set, then this one wins. void setIgnoreAllWarnings(bool Val) { IgnoreAllWarnings = Val; } bool getIgnoreAllWarnings() const { return IgnoreAllWarnings; } - /// setEnableAllWarnings - When set to true, any unmapped ignored warnings - /// are no longer ignored. If this and IgnoreAllWarnings are both set, - /// then that one wins. + /// \brief When set to true, any unmapped ignored warnings are no longer + /// ignored. + /// + /// If this and IgnoreAllWarnings are both set, then that one wins. void setEnableAllWarnings(bool Val) { EnableAllWarnings = Val; } bool getEnableAllWarnngs() const { return EnableAllWarnings; } - /// setWarningsAsErrors - When set to true, any warnings reported are issued - /// as errors. + /// \brief When set to true, any warnings reported are issued as errors. void setWarningsAsErrors(bool Val) { WarningsAsErrors = Val; } bool getWarningsAsErrors() const { return WarningsAsErrors; } - /// setErrorsAsFatal - When set to true, any error reported is made a - /// fatal error. + /// \brief When set to true, any error reported is made a fatal error. void setErrorsAsFatal(bool Val) { ErrorsAsFatal = Val; } bool getErrorsAsFatal() const { return ErrorsAsFatal; } - /// setSuppressSystemWarnings - When set to true mask warnings that - /// come from system headers. + /// \brief When set to true mask warnings that come from system headers. void setSuppressSystemWarnings(bool Val) { SuppressSystemWarnings = Val; } bool getSuppressSystemWarnings() const { return SuppressSystemWarnings; } @@ -460,29 +472,34 @@ public: bool getShowColors() { return ShowColors; } /// \brief Specify which overload candidates to show when overload resolution - /// fails. By default, we show all candidates. + /// fails. + /// + /// By default, we show all candidates. void setShowOverloads(OverloadsShown Val) { ShowOverloads = Val; } OverloadsShown getShowOverloads() const { return ShowOverloads; } - /// \brief Pretend that the last diagnostic issued was ignored. This can - /// be used by clients who suppress diagnostics themselves. + /// \brief Pretend that the last diagnostic issued was ignored. + /// + /// This can be used by clients who suppress diagnostics themselves. void setLastDiagnosticIgnored() { LastDiagLevel = DiagnosticIDs::Ignored; } - /// setExtensionHandlingBehavior - This controls whether otherwise-unmapped - /// extension diagnostics are mapped onto ignore/warning/error. This - /// corresponds to the GCC -pedantic and -pedantic-errors option. + /// \brief Controls whether otherwise-unmapped extension diagnostics are + /// mapped onto ignore/warning/error. + /// + /// This corresponds to the GCC -pedantic and -pedantic-errors option. void setExtensionHandlingBehavior(ExtensionHandling H) { ExtBehavior = H; } ExtensionHandling getExtensionHandlingBehavior() const { return ExtBehavior; } - /// AllExtensionsSilenced - This is a counter bumped when an __extension__ - /// block is encountered. When non-zero, all extension diagnostics are - /// entirely silenced, no matter how they are mapped. + /// \brief Counter bumped when an __extension__ block is/ encountered. + /// + /// When non-zero, all extension diagnostics are entirely silenced, no + /// matter how they are mapped. void IncrementAllExtensionsSilenced() { ++AllExtensionsSilenced; } void DecrementAllExtensionsSilenced() { --AllExtensionsSilenced; } bool hasAllExtensionsSilenced() { return AllExtensionsSilenced != 0; } @@ -668,9 +685,9 @@ private: enum { /// \brief The maximum number of arguments we can hold. /// - /// We currently - /// only support up to 10 arguments (%0-%9). A single diagnostic with more - /// than that almost certainly has to be simplified anyway. + /// We currently only support up to 10 arguments (%0-%9). A single + /// diagnostic with more than that almost certainly has to be simplified + /// anyway. MaxArguments = 10, /// \brief The maximum number of ranges we can hold. @@ -687,12 +704,14 @@ private: /// \brief The number of hints in the DiagFixItHints array. unsigned char NumDiagFixItHints; - /// DiagArgumentsKind - This is an array of ArgumentKind::ArgumentKind enum - /// values, with one for each argument. This specifies whether the argument - /// is in DiagArgumentsStr or in DiagArguments. + /// \brief Specifies whether an argument is in DiagArgumentsStr or + /// in DiagArguments. + /// + /// This is an array of ArgumentKind::ArgumentKind enum values, one for each + /// argument. unsigned char DiagArgumentsKind[MaxArguments]; - /// \brief holds the values of each string argument for the current + /// \brief Holds the values of each string argument for the current /// diagnostic. /// /// This is only used when the corresponding ArgumentKind is ak_std_string. @@ -780,7 +799,7 @@ public: return Diag.TrapNumUnrecoverableErrorsOccurred > NumUnrecoverableErrors; } - // Set to initial state of "no errors occurred". + /// \brief Set to initial state of "no errors occurred". void reset() { NumErrors = Diag.TrapNumErrorsOccurred; NumUnrecoverableErrors = Diag.TrapNumUnrecoverableErrorsOccurred; @@ -890,9 +909,13 @@ public: Emit(); } - /// Operator bool: conversion of DiagnosticBuilder to bool always returns - /// true. This allows is to be used in boolean error contexts like: + /// \brief Conversion of DiagnosticBuilder to bool always returns \c true. + /// + /// This allows is to be used in boolean error contexts (where \c true is + /// used to indicate that an error has occurred), like: + /// \code /// return Diag(...); + /// \endcode operator bool() const { return true; } void AddString(StringRef S) const { @@ -1029,61 +1052,71 @@ public: unsigned getNumArgs() const { return DiagObj->NumDiagArgs; } - /// getArgKind - Return the kind of the specified index. Based on the kind - /// of argument, the accessors below can be used to get the value. + /// \brief Return the kind of the specified index. + /// + /// Based on the kind of argument, the accessors below can be used to get + /// the value. + /// + /// \pre Idx < getNumArgs() DiagnosticsEngine::ArgumentKind getArgKind(unsigned Idx) const { assert(Idx < getNumArgs() && "Argument index out of range!"); return (DiagnosticsEngine::ArgumentKind)DiagObj->DiagArgumentsKind[Idx]; } - /// getArgStdStr - Return the provided argument string specified by Idx. + /// \brief Return the provided argument string specified by \p Idx. + /// \pre getArgKind(Idx) == DiagnosticsEngine::ak_std_string const std::string &getArgStdStr(unsigned Idx) const { assert(getArgKind(Idx) == DiagnosticsEngine::ak_std_string && "invalid argument accessor!"); return DiagObj->DiagArgumentsStr[Idx]; } - /// getArgCStr - Return the specified C string argument. + /// \brief Return the specified C string argument. + /// \pre getArgKind(Idx) == DiagnosticsEngine::ak_c_string const char *getArgCStr(unsigned Idx) const { assert(getArgKind(Idx) == DiagnosticsEngine::ak_c_string && "invalid argument accessor!"); return reinterpret_cast(DiagObj->DiagArgumentsVal[Idx]); } - /// getArgSInt - Return the specified signed integer argument. + /// \brief Return the specified signed integer argument. + /// \pre getArgKind(Idx) == DiagnosticsEngine::ak_sint int getArgSInt(unsigned Idx) const { assert(getArgKind(Idx) == DiagnosticsEngine::ak_sint && "invalid argument accessor!"); return (int)DiagObj->DiagArgumentsVal[Idx]; } - /// getArgUInt - Return the specified unsigned integer argument. + /// \brief Return the specified unsigned integer argument. + /// \pre getArgKind(Idx) == DiagnosticsEngine::ak_uint unsigned getArgUInt(unsigned Idx) const { assert(getArgKind(Idx) == DiagnosticsEngine::ak_uint && "invalid argument accessor!"); return (unsigned)DiagObj->DiagArgumentsVal[Idx]; } - /// getArgIdentifier - Return the specified IdentifierInfo argument. + /// \brief Return the specified IdentifierInfo argument. + /// \pre getArgKind(Idx) == DiagnosticsEngine::ak_identifierinfo const IdentifierInfo *getArgIdentifier(unsigned Idx) const { assert(getArgKind(Idx) == DiagnosticsEngine::ak_identifierinfo && "invalid argument accessor!"); return reinterpret_cast(DiagObj->DiagArgumentsVal[Idx]); } - /// getRawArg - Return the specified non-string argument in an opaque form. + /// \brief Return the specified non-string argument in an opaque form. + /// \pre getArgKind(Idx) != DiagnosticsEngine::ak_std_string intptr_t getRawArg(unsigned Idx) const { assert(getArgKind(Idx) != DiagnosticsEngine::ak_std_string && "invalid argument accessor!"); return DiagObj->DiagArgumentsVal[Idx]; } - /// getNumRanges - Return the number of source ranges associated with this - /// diagnostic. + /// \brief Return the number of source ranges associated with this diagnostic. unsigned getNumRanges() const { return DiagObj->NumDiagRanges; } + /// \pre Idx < getNumRanges() const CharSourceRange &getRange(unsigned Idx) const { assert(Idx < DiagObj->NumDiagRanges && "Invalid diagnostic range index!"); return DiagObj->DiagRanges[Idx]; @@ -1107,13 +1140,14 @@ public: return getNumFixItHints()? DiagObj->DiagFixItHints : 0; } - /// FormatDiagnostic - Format this diagnostic into a string, substituting the - /// formal arguments into the %0 slots. The result is appended onto the Str - /// array. + /// \brief Format this diagnostic into a string, substituting the + /// formal arguments into the %0 slots. + /// + /// The result is appended onto the \p OutStr array. void FormatDiagnostic(SmallVectorImpl &OutStr) const; - /// FormatDiagnostic - Format the given format-string into the - /// output buffer using the arguments stored in this diagnostic. + /// \brief Format the given format-string into the output buffer using the + /// arguments stored in this diagnostic. void FormatDiagnostic(const char *DiagStr, const char *DiagEnd, SmallVectorImpl &OutStr) const; }; @@ -1171,12 +1205,12 @@ public: } }; -/// DiagnosticConsumer - This is an abstract interface implemented by clients of -/// the front-end, which formats and prints fully processed diagnostics. +/// \brief Abstract interface, implemented by clients of the front-end, which +/// formats and prints fully processed diagnostics. class DiagnosticConsumer { protected: - unsigned NumWarnings; // Number of warnings reported - unsigned NumErrors; // Number of errors reported + unsigned NumWarnings; ///< Number of warnings reported + unsigned NumErrors; ///< Number of errors reported public: DiagnosticConsumer() : NumWarnings(0), NumErrors(0) { } @@ -1187,7 +1221,7 @@ public: virtual ~DiagnosticConsumer(); - /// BeginSourceFile - Callback to inform the diagnostic client that processing + /// \brief Callback to inform the diagnostic client that processing /// of a source file is beginning. /// /// Note that diagnostics may be emitted outside the processing of a source @@ -1195,32 +1229,35 @@ public: /// diagnostics with source range information are required to only be emitted /// in between BeginSourceFile() and EndSourceFile(). /// - /// \arg LO - The language options for the source file being processed. - /// \arg PP - The preprocessor object being used for the source; this optional - /// and may not be present, for example when processing AST source files. + /// \param LangOpts The language options for the source file being processed. + /// \param PP The preprocessor object being used for the source; this is + /// optional, e.g., it may not be present when processing AST source files. virtual void BeginSourceFile(const LangOptions &LangOpts, const Preprocessor *PP = 0) {} - /// EndSourceFile - Callback to inform the diagnostic client that processing - /// of a source file has ended. The diagnostic client should assume that any - /// objects made available via \see BeginSourceFile() are inaccessible. + /// \brief Callback to inform the diagnostic client that processing + /// of a source file has ended. + /// + /// The diagnostic client should assume that any objects made available via + /// BeginSourceFile() are inaccessible. virtual void EndSourceFile() {} /// \brief Callback to inform the diagnostic client that processing of all /// source files has ended. virtual void finish() {} - /// IncludeInDiagnosticCounts - This method (whose default implementation - /// returns true) indicates whether the diagnostics handled by this + /// \brief Indicates whether the diagnostics handled by this /// DiagnosticConsumer should be included in the number of diagnostics /// reported by DiagnosticsEngine. + /// + /// The default implementation returns true. virtual bool IncludeInDiagnosticCounts() const; - /// HandleDiagnostic - Handle this diagnostic, reporting it to the user or + /// \brief Handle this diagnostic, reporting it to the user or /// capturing it to a log as needed. /// - /// Default implementation just keeps track of the total number of warnings - /// and errors. + /// The default implementation just keeps track of the total number of + /// warnings and errors. virtual void HandleDiagnostic(DiagnosticsEngine::Level DiagLevel, const Diagnostic &Info); @@ -1229,8 +1266,7 @@ public: virtual DiagnosticConsumer *clone(DiagnosticsEngine &Diags) const = 0; }; -/// IgnoringDiagConsumer - This is a diagnostic client that just ignores all -/// diags. +/// \brief A diagnostic client that ignores all diagnostics. class IgnoringDiagConsumer : public DiagnosticConsumer { virtual void anchor(); void HandleDiagnostic(DiagnosticsEngine::Level DiagLevel, diff --git a/clang/include/clang/Basic/DiagnosticIDs.h b/clang/include/clang/Basic/DiagnosticIDs.h index 532de5ed0653..3642da11976a 100644 --- a/clang/include/clang/Basic/DiagnosticIDs.h +++ b/clang/include/clang/Basic/DiagnosticIDs.h @@ -45,7 +45,7 @@ namespace clang { class CustomDiagInfo; - /// diag::kind - All of the diagnostics that can be emitted by the frontend. + /// \brief All of the diagnostics that can be emitted by the frontend. typedef unsigned kind; // Get typedefs for common diagnostics. @@ -112,80 +112,81 @@ public: /// by multiple Diagnostics for multiple translation units. class DiagnosticIDs : public RefCountedBase { public: - /// Level - The level of the diagnostic, after it has been through mapping. + /// Level The level of the diagnostic, after it has been through mapping. enum Level { Ignored, Note, Warning, Error, Fatal }; private: - /// CustomDiagInfo - Information for uniquing and looking up custom diags. + /// \brief Information for uniquing and looking up custom diags. diag::CustomDiagInfo *CustomDiagInfo; public: DiagnosticIDs(); ~DiagnosticIDs(); - /// getCustomDiagID - Return an ID for a diagnostic with the specified message - /// and level. If this is the first request for this diagnosic, it is - /// registered and created, otherwise the existing ID is returned. + /// \brief Return an ID for a diagnostic with the specified message and level. + /// + /// If this is the first request for this diagnosic, it is registered and + /// created, otherwise the existing ID is returned. unsigned getCustomDiagID(Level L, StringRef Message); //===--------------------------------------------------------------------===// // Diagnostic classification and reporting interfaces. // - /// getDescription - Given a diagnostic ID, return a description of the - /// issue. + /// \brief Given a diagnostic ID, return a description of the issue. StringRef getDescription(unsigned DiagID) const; - /// isBuiltinWarningOrExtension - Return true if the unmapped diagnostic level - /// of the specified diagnostic ID is a Warning or Extension. This only works - /// on builtin diagnostics, not custom ones, and is not legal to call on - /// NOTEs. + /// \brief Return true if the unmapped diagnostic levelof the specified + /// diagnostic ID is a Warning or Extension. + /// + /// This only works on builtin diagnostics, not custom ones, and is not + /// legal to call on NOTEs. static bool isBuiltinWarningOrExtension(unsigned DiagID); /// \brief Return true if the specified diagnostic is mapped to errors by /// default. static bool isDefaultMappingAsError(unsigned DiagID); - /// \brief Determine whether the given built-in diagnostic ID is a - /// Note. + /// \brief Determine whether the given built-in diagnostic ID is a Note. static bool isBuiltinNote(unsigned DiagID); - /// isBuiltinExtensionDiag - Determine whether the given built-in diagnostic - /// ID is for an extension of some sort. - /// + /// \brief Determine whether the given built-in diagnostic ID is for an + /// extension of some sort. static bool isBuiltinExtensionDiag(unsigned DiagID) { bool ignored; return isBuiltinExtensionDiag(DiagID, ignored); } - /// isBuiltinExtensionDiag - Determine whether the given built-in diagnostic - /// ID is for an extension of some sort. This also returns EnabledByDefault, - /// which is set to indicate whether the diagnostic is ignored by default (in - /// which case -pedantic enables it) or treated as a warning/error by default. + /// \brief Determine whether the given built-in diagnostic ID is for an + /// extension of some sort, and whether it is enabled by default. + /// + /// This also returns EnabledByDefault, which is set to indicate whether the + /// diagnostic is ignored by default (in which case -pedantic enables it) or + /// treated as a warning/error by default. /// static bool isBuiltinExtensionDiag(unsigned DiagID, bool &EnabledByDefault); - /// getWarningOptionForDiag - Return the lowest-level warning option that - /// enables the specified diagnostic. If there is no -Wfoo flag that controls - /// the diagnostic, this returns null. + /// \brief Return the lowest-level warning option that enables the specified + /// diagnostic. + /// + /// If there is no -Wfoo flag that controls the diagnostic, this returns null. static StringRef getWarningOptionForDiag(unsigned DiagID); - /// getCategoryNumberForDiag - Return the category number that a specified - /// DiagID belongs to, or 0 if no category. + /// \brief Return the category number that a specified \p DiagID belongs to, + /// or 0 if no category. static unsigned getCategoryNumberForDiag(unsigned DiagID); - /// getNumberOfCategories - Return the number of categories + /// \brief Return the number of diagnostic categories. static unsigned getNumberOfCategories(); - /// getCategoryNameFromID - Given a category ID, return the name of the - /// category. + /// \brief Given a category ID, return the name of the category. static StringRef getCategoryNameFromID(unsigned CategoryID); - /// isARCDiagnostic - Return true if a given diagnostic falls into an - /// ARC diagnostic category; + /// \brief Return true if a given diagnostic falls into an ARC diagnostic + /// category. static bool isARCDiagnostic(unsigned DiagID); /// \brief Enumeration describing how the the emission of a diagnostic should @@ -254,17 +255,16 @@ private: DiagnosticIDs::Level getDiagnosticLevel(unsigned DiagID, SourceLocation Loc, const DiagnosticsEngine &Diag) const; - /// getDiagnosticLevel - This is an internal implementation helper used when - /// DiagClass is already known. + /// \brief An internal implementation helper used when \p DiagClass is + /// already known. DiagnosticIDs::Level getDiagnosticLevel(unsigned DiagID, unsigned DiagClass, SourceLocation Loc, const DiagnosticsEngine &Diag) const; - /// ProcessDiag - This is the method used to report a diagnostic that is - /// finally fully formed. + /// \brief Used to report a diagnostic that is finally fully formed. /// - /// \returns true if the diagnostic was emitted, false if it was + /// \returns \c true if the diagnostic was emitted, \c false if it was /// suppressed. bool ProcessDiag(DiagnosticsEngine &Diag) const; diff --git a/clang/include/clang/Basic/FileManager.h b/clang/include/clang/Basic/FileManager.h index 9017f4147d30..deb9caf4661e 100644 --- a/clang/include/clang/Basic/FileManager.h +++ b/clang/include/clang/Basic/FileManager.h @@ -41,9 +41,8 @@ namespace clang { class FileManager; class FileSystemStatCache; -/// DirectoryEntry - Cached information about one directory (either on -/// the disk or in the virtual file system). -/// +/// \brief Cached information about one directory (either on disk or in +/// the virtual file system). class DirectoryEntry { const char *Name; // Name of the directory. friend class FileManager; @@ -52,10 +51,11 @@ public: const char *getName() const { return Name; } }; -/// FileEntry - Cached information about one file (either on the disk -/// or in the virtual file system). If the 'FD' member is valid, then -/// this FileEntry has an open file descriptor for the file. +/// \brief Cached information about one file (either on disk +/// or in the virtual file system). /// +/// If the 'FD' member is valid, then this FileEntry has an open file +/// descriptor for the file. class FileEntry { const char *Name; // Name of the file. off_t Size; // File size in bytes. @@ -97,8 +97,7 @@ public: time_t getModificationTime() const { return ModTime; } mode_t getFileMode() const { return FileMode; } - /// getDir - Return the directory the file lives in. - /// + /// \brief Return the directory the file lives in. const DirectoryEntry *getDir() const { return Dir; } bool operator<(const FileEntry &RHS) const { @@ -106,10 +105,12 @@ public: } }; -/// FileManager - Implements support for file system lookup, file system -/// caching, and directory search management. This also handles more advanced -/// properties, such as uniquing files based on "inode", so that a file with two -/// names (e.g. symlinked) will be treated as a single file. +/// \brief Implements support for file system lookup, file system caching, +/// and directory search management. +/// +/// This also handles more advanced properties, such as uniquing files based +/// on "inode", so that a file with two names (e.g. symlinked) will be treated +/// as a single file. /// class FileManager : public RefCountedBase { FileSystemOptions FileSystemOpts; @@ -117,30 +118,37 @@ class FileManager : public RefCountedBase { class UniqueDirContainer; class UniqueFileContainer; - /// UniqueRealDirs/UniqueRealFiles - Cache for existing real - /// directories/files. - /// + /// \brief Cache for existing real directories. UniqueDirContainer &UniqueRealDirs; + + /// \brief Cache for existing real files. UniqueFileContainer &UniqueRealFiles; - /// \brief The virtual directories that we have allocated. For each - /// virtual file (e.g. foo/bar/baz.cpp), we add all of its parent + /// \brief The virtual directories that we have allocated. + /// + /// For each virtual file (e.g. foo/bar/baz.cpp), we add all of its parent /// directories (foo/ and foo/bar/) here. SmallVector VirtualDirectoryEntries; /// \brief The virtual files that we have allocated. SmallVector VirtualFileEntries; - /// SeenDirEntries/SeenFileEntries - This is a cache that maps paths - /// to directory/file entries (either real or virtual) we have - /// looked up. The actual Entries for real directories/files are + /// \brief A cache that maps paths to directory entries (either real or + /// virtual) we have looked up + /// + /// The actual Entries for real directories/files are /// owned by UniqueRealDirs/UniqueRealFiles above, while the Entries /// for virtual directories/files are owned by /// VirtualDirectoryEntries/VirtualFileEntries above. /// llvm::StringMap SeenDirEntries; + + /// \brief A cache that maps paths to file entries (either real or + /// virtual) we have looked up. + /// + /// \see SeenDirEntries llvm::StringMap SeenFileEntries; - /// NextFileUID - Each FileEntry we create is assigned a unique ID #. + /// \brief Each FileEntry we create is assigned a unique ID #. /// unsigned NextFileUID; @@ -217,13 +225,13 @@ public: llvm::MemoryBuffer *getBufferForFile(StringRef Filename, std::string *ErrorStr = 0); - /// \brief get the 'stat' information for the given path. + /// \brief Get the 'stat' information for the given \p Path. /// /// If the path is relative, it will be resolved against the WorkingDir of the /// FileManager's FileSystemOptions. bool getNoncachedStatValue(StringRef Path, struct stat &StatBuf); - /// \brief Remove the real file Entry from the cache. + /// \brief Remove the real file \p Entry from the cache. void InvalidateCache(const FileEntry* Entry); /// \brief If path is not absolute and FileSystemOptions set the working diff --git a/clang/include/clang/Basic/FileSystemStatCache.h b/clang/include/clang/Basic/FileSystemStatCache.h index b39755b7c180..a802c7cc748e 100644 --- a/clang/include/clang/Basic/FileSystemStatCache.h +++ b/clang/include/clang/Basic/FileSystemStatCache.h @@ -39,9 +39,10 @@ public: CacheMissing ///< We know that the file doesn't exist. }; - /// FileSystemStatCache::get - Get the 'stat' information for the specified - /// path, using the cache to accellerate it if possible. This returns true if - /// the path does not exist or false if it exists. + /// \brief Get the 'stat' information for the specified path, using the cache + /// to accelerate it if possible. + /// + /// \returns \c true if the path does not exist or \c false if it exists. /// /// If FileDescriptor is non-null, then this lookup should only return success /// for files (not directories). If it is null this lookup should only return diff --git a/clang/include/clang/Basic/IdentifierTable.h b/clang/include/clang/Basic/IdentifierTable.h index f668e6ec4d1a..dc6acdaa91ae 100644 --- a/clang/include/clang/Basic/IdentifierTable.h +++ b/clang/include/clang/Basic/IdentifierTable.h @@ -38,11 +38,11 @@ namespace clang { class MultiKeywordSelector; // private class used by Selector class DeclarationName; // AST class that stores declaration names - /// IdentifierLocPair - A simple pair of identifier info and location. + /// \brief A simple pair of identifier info and location. typedef std::pair IdentifierLocPair; -/// IdentifierInfo - One of these records is kept for each identifier that +/// One of these records is kept for each identifier that /// is lexed. This contains information about whether the token was \#define'd, /// is a language keyword, or if it is a front-end token of some sort (e.g. a /// variable or function name). The preprocessor keeps this information in a @@ -402,10 +402,11 @@ public: virtual IdentifierInfo *GetIdentifier(unsigned ID) = 0; }; -/// IdentifierTable - This table implements an efficient mapping from strings to -/// IdentifierInfo nodes. It has no other purpose, but this is an -/// extremely performance-critical piece of the code, as each occurrence of -/// every identifier goes through here when lexed. +/// \brief Implements an efficient mapping from strings to IdentifierInfo nodes. +/// +/// This has no other purpose, but this is an extremely performance-critical +/// piece of the code, as each occurrence of every identifier goes through +/// here when lexed. class IdentifierTable { // Shark shows that using MallocAllocator is *much* slower than using this // BumpPtrAllocator! @@ -415,8 +416,8 @@ class IdentifierTable { IdentifierInfoLookup* ExternalLookup; public: - /// IdentifierTable ctor - Create the identifier table, populating it with - /// info about the language keywords for the language specified by LangOpts. + /// \brief Create the identifier table, populating it with info about the + /// language keywords for the language specified by \p LangOpts. IdentifierTable(const LangOptions &LangOpts, IdentifierInfoLookup* externalLookup = 0); @@ -434,8 +435,8 @@ public: return HashTable.getAllocator(); } - /// get - Return the identifier token info for the specified named identifier. - /// + /// \brief Return the identifier token info for the specified named + /// identifier. IdentifierInfo &get(StringRef Name) { llvm::StringMapEntry &Entry = HashTable.GetOrCreateValue(Name); @@ -509,15 +510,16 @@ public: iterator end() const { return HashTable.end(); } unsigned size() const { return HashTable.size(); } - /// PrintStats - Print some statistics to stderr that indicate how well the + /// \brief Print some statistics to stderr that indicate how well the /// hashing is doing. void PrintStats() const; void AddKeywords(const LangOptions &LangOpts); }; -/// ObjCMethodFamily - A family of Objective-C methods. These -/// families have no inherent meaning in the language, but are +/// \brief A family of Objective-C methods. +/// +/// These families have no inherent meaning in the language, but are /// nonetheless central enough in the existing implementations to /// merit direct AST support. While, in theory, arbitrary methods can /// be considered to form families, we focus here on the methods @@ -564,11 +566,13 @@ enum ObjCMethodFamily { /// InvalidObjCMethodFamily. enum { ObjCMethodFamilyBitWidth = 4 }; -/// An invalid value of ObjCMethodFamily. +/// \brief An invalid value of ObjCMethodFamily. enum { InvalidObjCMethodFamily = (1 << ObjCMethodFamilyBitWidth) - 1 }; -/// Selector - This smart pointer class efficiently represents Objective-C -/// method names. This class will either point to an IdentifierInfo or a +/// \brief Smart pointer class that efficiently represents Objective-C method +/// names. +/// +/// This class will either point to an IdentifierInfo or a /// MultiKeywordSelector (which is private). This enables us to optimize /// selectors that take no arguments and selectors that take 1 argument, which /// accounts for 78% of all selectors in Cocoa.h. @@ -669,12 +673,12 @@ public: /// name was supplied. StringRef getNameForSlot(unsigned argIndex) const; - /// getAsString - Derive the full selector name (e.g. "foo:bar:") and return + /// \brief Derive the full selector name (e.g. "foo:bar:") and return /// it as an std::string. // FIXME: Add a print method that uses a raw_ostream. std::string getAsString() const; - /// getMethodFamily - Derive the conventional family of this method. + /// \brief Derive the conventional family of this method. ObjCMethodFamily getMethodFamily() const { return getMethodFamilyImpl(*this); } @@ -687,7 +691,7 @@ public: } }; -/// SelectorTable - This table allows us to fully hide how we implement +/// \brief This table allows us to fully hide how we implement /// multi-keyword caching. class SelectorTable { void *Impl; // Actually a SelectorTableImpl @@ -697,9 +701,10 @@ public: SelectorTable(); ~SelectorTable(); - /// getSelector - This can create any sort of selector. NumArgs indicates - /// whether this is a no argument selector "foo", a single argument selector - /// "foo:" or multi-argument "foo:bar:". + /// \brief Can create any sort of selector. + /// + /// \p NumArgs indicates whether this is a no argument selector "foo", a + /// single argument selector "foo:" or multi-argument "foo:bar:". Selector getSelector(unsigned NumArgs, IdentifierInfo **IIV); Selector getUnarySelector(IdentifierInfo *ID) { @@ -709,11 +714,12 @@ public: return Selector(ID, 0); } - /// Return the total amount of memory allocated for managing selectors. + /// \brief Return the total amount of memory allocated for managing selectors. size_t getTotalMemory() const; - /// constructSetterName - Return the setter name for the given - /// identifier, i.e. "set" + Name where the initial character of Name + /// \brief Return the setter name for the given identifier. + /// + /// This is "set" + \p Name where the initial character of \p Name /// has been capitalized. static Selector constructSetterName(IdentifierTable &Idents, SelectorTable &SelTable, diff --git a/clang/include/clang/Basic/Lambda.h b/clang/include/clang/Basic/Lambda.h index 0014ed26e1f3..b1ad6acda3b4 100644 --- a/clang/include/clang/Basic/Lambda.h +++ b/clang/include/clang/Basic/Lambda.h @@ -19,16 +19,15 @@ namespace clang { -/// LambdaCaptureDefault - The default, if any, capture method for a -/// lambda expression. +/// \brief The default, if any, capture method for a lambda expression. enum LambdaCaptureDefault { LCD_None, LCD_ByCopy, LCD_ByRef }; -/// LambdaCaptureKind - The different capture forms in a lambda -/// introducer: 'this' or a copied or referenced variable. +/// \brief The different capture forms in a lambda introducer: 'this' or a +/// copied or referenced variable. enum LambdaCaptureKind { LCK_This, LCK_ByCopy, diff --git a/clang/include/clang/Basic/LangOptions.h b/clang/include/clang/Basic/LangOptions.h index 2edb556afe5a..10f496fd39fa 100644 --- a/clang/include/clang/Basic/LangOptions.h +++ b/clang/include/clang/Basic/LangOptions.h @@ -41,8 +41,8 @@ protected: #include "clang/Basic/LangOptions.def" }; -/// LangOptions - This class keeps track of the various options that can be -/// enabled, which controls the dialect of C that is accepted. +/// \brief Keeps track of the various options that can be +/// enabled, which controls the dialect of C or C++ that is accepted. class LangOptions : public RefCountedBase, public LangOptionsBase { public: typedef clang::Visibility Visibility; @@ -61,7 +61,9 @@ public: std::string ObjCConstantStringClass; - /// The name of the handler function to be called when -ftrapv is specified. + /// \brief The name of the handler function to be called when -ftrapv is + /// specified. + /// /// If none is specified, abort (GCC-compatible behaviour). std::string OverflowHandler; @@ -86,7 +88,7 @@ public: void resetNonModularOptions(); }; -/// Floating point control options +/// \brief Floating point control options class FPOptions { public: unsigned fp_contract : 1; @@ -97,7 +99,7 @@ public: fp_contract(LangOpts.DefaultFPContract) {} }; -/// OpenCL volatile options +/// \brief OpenCL volatile options class OpenCLOptions { public: #define OPENCLEXT(nm) unsigned nm : 1; @@ -120,7 +122,6 @@ enum TranslationUnitKind { TU_Module }; - /// \brief } // end namespace clang #endif diff --git a/clang/include/clang/Basic/Linkage.h b/clang/include/clang/Basic/Linkage.h index 7922813ff887..6bc1f5d5ef1c 100644 --- a/clang/include/clang/Basic/Linkage.h +++ b/clang/include/clang/Basic/Linkage.h @@ -28,8 +28,9 @@ enum Linkage { /// translation units). InternalLinkage, - /// \brief External linkage within a unique namespace. From the - /// language perspective, these entities have external + /// \brief External linkage within a unique namespace. + /// + /// From the language perspective, these entities have external /// linkage. However, since they reside in an anonymous namespace, /// their names are unique to this translation unit, which is /// equivalent to having internal linkage from the code-generation @@ -41,8 +42,9 @@ enum Linkage { ExternalLinkage }; -/// \brief A more specific kind of linkage. This is relevant to CodeGen and -/// AST file reading. +/// \brief A more specific kind of linkage than enum Linkage. +/// +/// This is relevant to CodeGen and AST file reading. enum GVALinkage { GVA_Internal, GVA_C99Inline, @@ -52,8 +54,7 @@ enum GVALinkage { GVA_ExplicitTemplateInstantiation }; -/// \brief Determine whether the given linkage is semantically -/// external. +/// \brief Determine whether the given linkage is semantically external. inline bool isExternalLinkage(Linkage L) { return L == UniqueExternalLinkage || L == ExternalLinkage; } diff --git a/clang/include/clang/Basic/ObjCRuntime.h b/clang/include/clang/Basic/ObjCRuntime.h index 13f13075fab2..1be3b142c3ef 100644 --- a/clang/include/clang/Basic/ObjCRuntime.h +++ b/clang/include/clang/Basic/ObjCRuntime.h @@ -20,10 +20,10 @@ namespace clang { -/// The basic abstraction for the target ObjC runtime. +/// \brief The basic abstraction for the target Objective-C runtime. class ObjCRuntime { public: - /// The basic Objective-C runtimes that we know about. + /// \brief The basic Objective-C runtimes that we know about. enum Kind { /// 'macosx' is the Apple-provided NeXT-derived runtime on Mac OS /// X platforms that use the non-fragile ABI; the version is a @@ -66,7 +66,7 @@ public: Kind getKind() const { return TheKind; } const VersionTuple &getVersion() const { return Version; } - /// Does this runtime follow the set of implied behaviors for a + /// \brief Does this runtime follow the set of implied behaviors for a /// "non-fragile" ABI? bool isNonFragile() const { switch (getKind()) { @@ -79,11 +79,11 @@ public: llvm_unreachable("bad kind"); } - /// The inverse of isNonFragile(): does this runtiem follow the set of + /// The inverse of isNonFragile(): does this runtime follow the set of /// implied behaviors for a "fragile" ABI? bool isFragile() const { return !isNonFragile(); } - /// Is this runtime basically of the GNU family of runtimes? + /// \brief Is this runtime basically of the GNU family of runtimes? bool isGNUFamily() const { switch (getKind()) { case FragileMacOSX: @@ -97,15 +97,16 @@ public: llvm_unreachable("bad kind"); } - /// Is this runtime basically of the NeXT family of runtimes? + /// \brief Is this runtime basically of the NeXT family of runtimes? bool isNeXTFamily() const { // For now, this is just the inverse of isGNUFamily(), but that's // not inherently true. return !isGNUFamily(); } - /// Does this runtime natively provide the ARC entrypoints? ARC - /// cannot be directly supported on a platform that does not provide + /// \brief Does this runtime natively provide the ARC entrypoints? + /// + /// ARC cannot be directly supported on a platform that does not provide /// these entrypoints, although it may be supportable via a stub /// library. bool hasARC() const { @@ -123,14 +124,15 @@ public: llvm_unreachable("bad kind"); } - /// Does this runtime natively provide ARC-compliant 'weak' + /// \brief Does this runtime natively provide ARC-compliant 'weak' /// entrypoints? bool hasWeak() const { // Right now, this is always equivalent to the ARC decision. return hasARC(); } - /// Does this runtime directly support the subscripting methods? + /// \brief Does this runtime directly support the subscripting methods? + /// /// This is really a property of the library, not the runtime. bool hasSubscripting() const { switch (getKind()) { @@ -147,8 +149,9 @@ public: llvm_unreachable("bad kind"); } - /// Does this runtime provide an objc_terminate function? This is - /// used in handlers for exceptions during the unwind process; + /// \brief Does this runtime provide an objc_terminate function? + /// + /// This is used in handlers for exceptions during the unwind process; /// without it, abort() must be used in pure ObjC files. bool hasTerminate() const { switch (getKind()) { @@ -161,7 +164,7 @@ public: llvm_unreachable("bad kind"); } - /// Does this runtime support weakly importing classes? + /// \brief Does this runtime support weakly importing classes? bool hasWeakClassImport() const { switch (getKind()) { case MacOSX: return true; @@ -173,9 +176,10 @@ public: llvm_unreachable("bad kind"); } - /// Try to parse an Objective-C runtime specification from the given string. + /// \brief Try to parse an Objective-C runtime specification from the given + /// string. /// - /// Return true on error. + /// \return true on error. bool tryParse(StringRef input); std::string getAsString() const; diff --git a/clang/include/clang/Basic/OpenCL.h b/clang/include/clang/Basic/OpenCL.h index 5904a3fc154b..3b3f259252df 100644 --- a/clang/include/clang/Basic/OpenCL.h +++ b/clang/include/clang/Basic/OpenCL.h @@ -17,7 +17,7 @@ namespace clang { -/// Names for the OpenCL image access qualifiers (OpenCL 1.1 6.6). +/// \brief Names for the OpenCL image access qualifiers (OpenCL 1.1 6.6). enum OpenCLImageAccess { CLIA_read_only = 1, CLIA_write_only = 2, diff --git a/clang/include/clang/Basic/OperatorKinds.h b/clang/include/clang/Basic/OperatorKinds.h index 5900718644ac..108014faabe1 100644 --- a/clang/include/clang/Basic/OperatorKinds.h +++ b/clang/include/clang/Basic/OperatorKinds.h @@ -17,8 +17,8 @@ namespace clang { -/// OverloadedOperatorKind - Enumeration specifying the different kinds of -/// C++ overloaded operators. +/// \brief Enumeration specifying the different kinds of C++ overloaded +/// operators. enum OverloadedOperatorKind { OO_None, ///< Not an overloaded operator #define OVERLOADED_OPERATOR(Name,Spelling,Token,Unary,Binary,MemberOnly) \ diff --git a/clang/include/clang/Basic/PartialDiagnostic.h b/clang/include/clang/Basic/PartialDiagnostic.h index 8e12a14a5124..3f4626ec0a7e 100644 --- a/clang/include/clang/Basic/PartialDiagnostic.h +++ b/clang/include/clang/Basic/PartialDiagnostic.h @@ -38,25 +38,26 @@ public: Storage() : NumDiagArgs(0), NumDiagRanges(0) { } enum { - /// MaxArguments - The maximum number of arguments we can hold. We + /// \brief The maximum number of arguments we can hold. We /// currently only support up to 10 arguments (%0-%9). + /// /// A single diagnostic with more than that almost certainly has to /// be simplified anyway. MaxArguments = PartialDiagnostic::MaxArguments }; - /// NumDiagArgs - This contains the number of entries in Arguments. + /// \brief The number of entries in Arguments. unsigned char NumDiagArgs; - /// NumDiagRanges - This is the number of ranges in the DiagRanges array. + /// \brief This is the number of ranges in the DiagRanges array. unsigned char NumDiagRanges; - /// DiagArgumentsKind - This is an array of ArgumentKind::ArgumentKind enum - /// values, with one for each argument. This specifies whether the argument - /// is in DiagArgumentsStr or in DiagArguments. + /// \brief Specifies for each argument whether it is in DiagArgumentsStr + /// or in DiagArguments. unsigned char DiagArgumentsKind[MaxArguments]; - /// DiagArgumentsVal - The values for the various substitution positions. + /// \brief The values for the various substitution positions. + /// /// This is used when the argument is not an std::string. The specific value /// is mangled into an intptr_t and the interpretation depends on exactly /// what sort of argument kind it is. @@ -66,12 +67,13 @@ public: /// string arguments. std::string DiagArgumentsStr[MaxArguments]; - /// DiagRanges - The list of ranges added to this diagnostic. It currently - /// only support 10 ranges, could easily be extended if needed. + /// \brief The list of ranges added to this diagnostic. + /// + /// It currently only support 10 ranges, could easily be extended if needed. CharSourceRange DiagRanges[10]; - /// FixItHints - If valid, provides a hint with some code - /// to insert, remove, or modify at a particular position. + /// \brief If valid, provides a hint with some code to insert, remove, or + /// modify at a particular position. SmallVector FixItHints; }; @@ -115,10 +117,10 @@ private: // in the sense that its bits can be safely memcpy'ed and destructed // in the new location. - /// DiagID - The diagnostic ID. + /// \brief The diagnostic ID. mutable unsigned DiagID; - /// DiagStorage - Storage for args and ranges. + /// \brief Storage for args and ranges. mutable Storage *DiagStorage; /// \brief Allocator used to allocate storage for this diagnostic. diff --git a/clang/include/clang/Basic/PrettyStackTrace.h b/clang/include/clang/Basic/PrettyStackTrace.h index 2f8cba42f965..967d0d141e5b 100644 --- a/clang/include/clang/Basic/PrettyStackTrace.h +++ b/clang/include/clang/Basic/PrettyStackTrace.h @@ -22,8 +22,8 @@ namespace clang { - /// PrettyStackTraceLoc - If a crash happens while one of these objects are - /// live, the message is printed out along with the specified source location. + /// If a crash happens while one of these objects are live, the message + /// is printed out along with the specified source location. class PrettyStackTraceLoc : public llvm::PrettyStackTraceEntry { SourceManager &SM; SourceLocation Loc; diff --git a/clang/include/clang/Basic/SourceLocation.h b/clang/include/clang/Basic/SourceLocation.h index 453827ca2dd1..3bac26fbaecf 100644 --- a/clang/include/clang/Basic/SourceLocation.h +++ b/clang/include/clang/Basic/SourceLocation.h @@ -36,8 +36,8 @@ class SourceManager; /// source file (MemoryBuffer) along with its \#include path and \#line data. /// class FileID { - /// ID - Opaque identifier, 0 is "invalid". >0 is this module, <-1 is - /// something loaded from another module. + /// \brief A mostly-opaque identifier, where 0 is "invalid", >0 is + /// this module, and <-1 is something loaded from another module. int ID; public: FileID() : ID(0) {} @@ -186,7 +186,7 @@ inline bool operator<(const SourceLocation &LHS, const SourceLocation &RHS) { return LHS.getRawEncoding() < RHS.getRawEncoding(); } -/// SourceRange - a trival tuple used to represent a source range. +/// \brief A trival tuple used to represent a source range. class SourceRange { SourceLocation B; SourceLocation E; @@ -213,7 +213,8 @@ public: } }; -/// CharSourceRange - This class represents a character granular source range. +/// \brief Represents a character-granular source range. +/// /// The underlying SourceRange can either specify the starting/ending character /// of the range, or it can specify the start or the range and the start of the /// last token of the range (a "token range"). In the token range case, the @@ -247,7 +248,7 @@ public: return getCharRange(SourceRange(B, E)); } - /// isTokenRange - Return true if the end of this range specifies the start of + /// \brief Return true if the end of this range specifies the start of /// the last token. Return false if the end of this range specifies the last /// character in the range. bool isTokenRange() const { return IsTokenRange; } @@ -264,17 +265,19 @@ public: bool isInvalid() const { return !isValid(); } }; -/// FullSourceLoc - A SourceLocation and its associated SourceManager. Useful -/// for argument passing to functions that expect both objects. +/// \brief A SourceLocation and its associated SourceManager. +/// +/// This is useful for argument passing to functions that expect both objects. class FullSourceLoc : public SourceLocation { const SourceManager *SrcMgr; public: - /// Creates a FullSourceLoc where isValid() returns false. + /// \brief Creates a FullSourceLoc where isValid() returns \c false. explicit FullSourceLoc() : SrcMgr(0) {} explicit FullSourceLoc(SourceLocation Loc, const SourceManager &SM) : SourceLocation(Loc), SrcMgr(&SM) {} + /// \pre This FullSourceLoc has an associated SourceManager. const SourceManager &getManager() const { assert(SrcMgr && "SourceManager is NULL."); return *SrcMgr; @@ -295,13 +298,14 @@ public: const llvm::MemoryBuffer* getBuffer(bool *Invalid = 0) const; - /// getBufferData - Return a StringRef to the source buffer data for the + /// \brief Return a StringRef to the source buffer data for the /// specified FileID. StringRef getBufferData(bool *Invalid = 0) const; - /// getDecomposedLoc - Decompose the specified location into a raw FileID + - /// Offset pair. The first element is the FileID, the second is the - /// offset from the start of the buffer of the location. + /// \brief Decompose the specified location into a raw FileID + Offset pair. + /// + /// The first element is the FileID, the second is the offset from the + /// start of the buffer of the location. std::pair getDecomposedLoc() const; bool isInSystemHeader() const; @@ -328,8 +332,9 @@ public: } }; - /// Prints information about this FullSourceLoc to stderr. Useful for - /// debugging. + /// \brief Prints information about this FullSourceLoc to stderr. + /// + /// This is useful for debugging. LLVM_ATTRIBUTE_USED void dump() const; friend inline bool @@ -345,10 +350,11 @@ public: }; -/// PresumedLoc - This class represents an unpacked "presumed" location which -/// can be presented to the user. A 'presumed' location can be modified by -/// \#line and GNU line marker directives and is always the expansion point of -/// a normal location. +/// \brief Represents an unpacked "presumed" location which can be presented +/// to the user. +/// +/// A 'presumed' location can be modified by \#line and GNU line marker +/// directives and is always the expansion point of a normal location. /// /// You can get a PresumedLoc from a SourceLocation with SourceManager. class PresumedLoc { @@ -361,9 +367,10 @@ public: : Filename(FN), Line(Ln), Col(Co), IncludeLoc(IL) { } - /// isInvalid - Return true if this object is invalid or uninitialized. This - /// occurs when created with invalid source locations or when walking off - /// the top of a \#include stack. + /// \brief Return true if this object is invalid or uninitialized. + /// + /// This occurs when created with invalid source locations or when walking + /// off the top of a \#include stack. bool isInvalid() const { return Filename == 0; } bool isValid() const { return Filename != 0; } diff --git a/clang/include/clang/Basic/SourceManager.h b/clang/include/clang/Basic/SourceManager.h index d5657c70e179..0cb3b834d7ad 100644 --- a/clang/include/clang/Basic/SourceManager.h +++ b/clang/include/clang/Basic/SourceManager.h @@ -66,18 +66,20 @@ class ASTReader; /// SourceManager implementation. /// namespace SrcMgr { - /// CharacteristicKind - This is used to represent whether a file or directory - /// holds normal user code, system code, or system code which is implicitly - /// 'extern "C"' in C++ mode. Entire directories can be tagged with this - /// (this is maintained by DirectoryLookup and friends) as can specific - /// FileInfos when a \#pragma system_header is seen or various other cases. + /// \brief Indicates whether a file or directory holds normal user code, + /// system code, or system code which is implicitly 'extern "C"' in C++ mode. + /// + /// Entire directories can be tagged with this (this is maintained by + /// DirectoryLookup and friends) as can specific FileInfos when a \#pragma + /// system_header is seen or in various other cases. /// enum CharacteristicKind { C_User, C_System, C_ExternCSystem }; - /// ContentCache - One instance of this struct is kept for every file - /// loaded or used. This object owns the MemoryBuffer object. + /// \brief One instance of this struct is kept for every file loaded or used. + //// + /// This object owns the MemoryBuffer object. class ContentCache { enum CCFlags { /// \brief Whether the buffer is invalid. @@ -97,8 +99,9 @@ namespace SrcMgr { /// \brief Reference to the file entry representing this ContentCache. /// /// This reference does not own the FileEntry object. - /// It is possible for this to be NULL if - /// the ContentCache encapsulates an imaginary text buffer. + /// + /// It is possible for this to be NULL if the ContentCache encapsulates + /// an imaginary text buffer. const FileEntry *OrigEntry; /// \brief References the file which the contents were actually loaded from. @@ -284,12 +287,12 @@ namespace SrcMgr { class ExpansionInfo { // Really these are all SourceLocations. - /// SpellingLoc - Where the spelling for the token can be found. + /// \brief Where the spelling for the token can be found. unsigned SpellingLoc; - /// ExpansionLocStart/ExpansionLocEnd - In a macro expansion, these + /// In a macro expansion, ExpansionLocStart and ExpansionLocEnd /// indicate the start and end of the expansion. In object-like macros, - /// these will be the same. In a function-like macro expansion, the start + /// they will be the same. In a function-like macro expansion, the start /// will be the identifier and the end will be the ')'. Finally, in /// macro-argument instantiations, the end will be 'SourceLocation()', an /// invalid location. @@ -350,12 +353,12 @@ namespace SrcMgr { /// /// Given the code: /// \code - /// \#define F(x) f(x) + /// #define F(x) f(x) /// F(42); /// \endcode /// /// When expanding '\c F(42)', the '\c x' would call this with an - /// SpellingLoc pointing at '\c 42' anad an ExpansionLoc pointing at its + /// SpellingLoc pointing at '\c 42' and an ExpansionLoc pointing at its /// location in the definition of '\c F'. static ExpansionInfo createForMacroArg(SourceLocation SpellingLoc, SourceLocation ExpansionLoc) { @@ -427,19 +430,22 @@ public: /// The cache structure is complex enough to be worth breaking out of /// SourceManager. class IsBeforeInTranslationUnitCache { - /// L/R QueryFID - These are the FID's of the cached query. If these match up - /// with a subsequent query, the result can be reused. + /// \brief The FileID's of the cached query. + /// + /// If these match up with a subsequent query, the result can be reused. FileID LQueryFID, RQueryFID; - /// \brief True if LQueryFID was created before RQueryFID. This is used - /// to compare macro expansion locations. + /// \brief True if LQueryFID was created before RQueryFID. + /// + /// This is used to compare macro expansion locations. bool IsLQFIDBeforeRQFID; /// \brief The file found in common between the two \#include traces, i.e., /// the nearest common ancestor of the \#include tree. FileID CommonFID; - /// L/R CommonOffset - This is the offset of the previous query in CommonFID. + /// \brief The offset of the previous query in CommonFID. + /// /// Usually, this represents the location of the \#include for QueryFID, but /// if LQueryFID is a parent of RQueryFID (or vice versa) then these can be a /// random token in the parent. @@ -447,13 +453,15 @@ class IsBeforeInTranslationUnitCache { public: /// \brief Return true if the currently cached values match up with - /// the specified LHS/RHS query. If not, we can't use the cache. + /// the specified LHS/RHS query. + /// + /// If not, we can't use the cache. bool isCacheValid(FileID LHS, FileID RHS) const { return LQueryFID == LHS && RQueryFID == RHS; } /// \brief If the cache is valid, compute the result given the - /// specified offsets in the LHS/RHS FID's. + /// specified offsets in the LHS/RHS FileID's. bool getCachedResult(unsigned LOffset, unsigned ROffset) const { // If one of the query files is the common file, use the offset. Otherwise, // use the #include loc in the common file. @@ -471,7 +479,7 @@ public: return LOffset < ROffset; } - // Set up a new query. + /// \brief Set up a new query. void setQueryFIDs(FileID LHS, FileID RHS, bool isLFIDBeforeRFID) { assert(LHS != RHS); LQueryFID = LHS; @@ -593,7 +601,7 @@ class SourceManager : public RefCountedBase { /// \brief Holds information for \#line directives. /// - /// It is referenced by indices from SLocEntryTable. + /// This is referenced by indices from SLocEntryTable. LineTableInfo *LineTable; /// \brief These ivars serve as a cache used in the getLineNumber @@ -774,7 +782,7 @@ public: } /// \brief Disable overridding the contents of a file, previously enabled - /// with \see overrideFileContents. + /// with #overrideFileContents. /// /// This should be called before parsing has begun. void disableFileContentsOverride(const FileEntry *File); @@ -1464,15 +1472,14 @@ private: return getLoadedSLocEntry(static_cast(-ID - 2), Invalid); } - /// createExpansionLoc - Implements the common elements of storing an - /// expansion info struct into the SLocEntry table and producing a source - /// location that refers to it. + /// Implements the common elements of storing an expansion info struct into + /// the SLocEntry table and producing a source location that refers to it. SourceLocation createExpansionLocImpl(const SrcMgr::ExpansionInfo &Expansion, unsigned TokLength, int LoadedID = 0, unsigned LoadedOffset = 0); - /// isOffsetInFileID - Return true if the specified FileID contains the + /// \brief Return true if the specified FileID contains the /// specified SourceLocation offset. This is a very hot method. inline bool isOffsetInFileID(FileID FID, unsigned SLocOffset) const { const SrcMgr::SLocEntry &Entry = getSLocEntry(FID); @@ -1493,9 +1500,11 @@ private: return SLocOffset < getSLocEntry(FileID::get(FID.ID+1)).getOffset(); } - /// createFileID - Create a new fileID for the specified ContentCache and - /// include position. This works regardless of whether the ContentCache - /// corresponds to a file or some other input source. + /// \brief Create a new fileID for the specified ContentCache and + /// include position. + /// + /// This works regardless of whether the ContentCache corresponds to a + /// file or some other input source. FileID createFileID(const SrcMgr::ContentCache* File, SourceLocation IncludePos, SrcMgr::CharacteristicKind DirCharacter, @@ -1504,8 +1513,7 @@ private: const SrcMgr::ContentCache * getOrCreateContentCache(const FileEntry *SourceFile); - /// createMemBufferContentCache - Create a new ContentCache for the specified - /// memory buffer. + /// \brief Create a new ContentCache for the specified memory buffer. const SrcMgr::ContentCache* createMemBufferContentCache(const llvm::MemoryBuffer *Buf); diff --git a/clang/include/clang/Basic/SourceManagerInternals.h b/clang/include/clang/Basic/SourceManagerInternals.h index 012c63d1ce61..af95b78883fe 100644 --- a/clang/include/clang/Basic/SourceManagerInternals.h +++ b/clang/include/clang/Basic/SourceManagerInternals.h @@ -27,22 +27,23 @@ namespace clang { //===----------------------------------------------------------------------===// struct LineEntry { - /// FileOffset - The offset in this file that the line entry occurs at. + /// \brief The offset in this file that the line entry occurs at. unsigned FileOffset; - /// LineNo - The presumed line number of this line entry: \#line 4. + /// \brief The presumed line number of this line entry: \#line 4. unsigned LineNo; - /// FilenameID - The ID of the filename identified by this line entry: + /// \brief The ID of the filename identified by this line entry: /// \#line 4 "foo.c". This is -1 if not specified. int FilenameID; - /// Flags - Set the 0 if no flags, 1 if a system header, + /// \brief Set the 0 if no flags, 1 if a system header, SrcMgr::CharacteristicKind FileKind; - /// IncludeOffset - This is the offset of the virtual include stack location, - /// which is manipulated by GNU linemarker directives. If this is 0 then - /// there is no virtual \#includer. + /// \brief The offset of the virtual include stack location, + /// which is manipulated by GNU linemarker directives. + /// + /// If this is 0 then there is no virtual \#includer. unsigned IncludeOffset; static LineEntry get(unsigned Offs, unsigned Line, int Filename, @@ -72,11 +73,11 @@ inline bool operator<(unsigned Offset, const LineEntry &E) { return Offset < E.FileOffset; } -/// LineTableInfo - This class is used to hold and unique data used to -/// represent \#line information. +/// \brief Used to hold and unique data used to represent \#line information. class LineTableInfo { - /// FilenameIDs - This map is used to assign unique IDs to filenames in - /// \#line directives. This allows us to unique the filenames that + /// \brief Map used to assign unique IDs to filenames in \#line directives. + /// + /// This allows us to unique the filenames that /// frequently reoccur and reference them with indices. FilenameIDs holds /// the mapping from string -> ID, and FilenamesByID holds the mapping of ID /// to string. @@ -112,8 +113,9 @@ public: unsigned EntryExit, SrcMgr::CharacteristicKind FileKind); - /// FindNearestLineEntry - Find the line entry nearest to FID that is before - /// it. If there is no line entry before Offset in FID, return null. + /// \brief Find the line entry nearest to FID that is before it. + /// + /// If there is no line entry before \p Offset in \p FID, returns null. const LineEntry *FindNearestLineEntry(FileID FID, unsigned Offset); // Low-level access diff --git a/clang/include/clang/Basic/Specifiers.h b/clang/include/clang/Basic/Specifiers.h index ac81e56a8b29..96cada10571e 100644 --- a/clang/include/clang/Basic/Specifiers.h +++ b/clang/include/clang/Basic/Specifiers.h @@ -64,9 +64,8 @@ namespace clang { TST_error // erroneous type }; - /// WrittenBuiltinSpecs - Structure that packs information about the - /// type specifiers that were written in a particular type specifier - /// sequence. + /// \brief Structure that packs information about the type specifiers that + /// were written in a particular type specifier sequence. struct WrittenBuiltinSpecs { /*DeclSpec::TST*/ unsigned Type : 5; /*DeclSpec::TSS*/ unsigned Sign : 2; @@ -74,9 +73,8 @@ namespace clang { bool ModeAttr : 1; }; - /// AccessSpecifier - A C++ access specifier (public, private, - /// protected), plus the special value "none" which means - /// different things in different contexts. + /// \brief A C++ access specifier (public, private, protected), plus the + /// special value "none" which means different things in different contexts. enum AccessSpecifier { AS_public, AS_protected, @@ -84,24 +82,24 @@ namespace clang { AS_none }; - /// ExprValueKind - The categorization of expression values, - /// currently following the C++0x scheme. + /// \brief The categorization of expression values, currently following the + /// C++11 scheme. enum ExprValueKind { - /// An r-value expression (a pr-value in the C++0x taxonomy) + /// \brief An r-value expression (a pr-value in the C++11 taxonomy) /// produces a temporary value. VK_RValue, - /// An l-value expression is a reference to an object with + /// \brief An l-value expression is a reference to an object with /// independent storage. VK_LValue, - /// An x-value expression is a reference to an object with + /// \brief An x-value expression is a reference to an object with /// independent storage but which can be "moved", i.e. /// efficiently cannibalized for its resources. VK_XValue }; - /// A further classification of the kind of object referenced by an + /// \brief A further classification of the kind of object referenced by an /// l-value or x-value. enum ExprObjectKind { /// An ordinary object is located at an address in memory. @@ -113,13 +111,13 @@ namespace clang { /// A vector component is an element or range of elements on a vector. OK_VectorComponent, - /// An Objective C property is a logical field of an Objective-C - /// object which is read and written via Objective C method calls. + /// An Objective-C property is a logical field of an Objective-C + /// object which is read and written via Objective-C method calls. OK_ObjCProperty, - /// An Objective C array/dictionary subscripting which reads an object - /// or writes at the subscripted array/dictionary element via - /// Objective C method calls. + /// An Objective-C array/dictionary subscripting which reads an + /// object or writes at the subscripted array/dictionary element via + /// Objective-C method calls. OK_ObjCSubscript }; @@ -160,12 +158,12 @@ namespace clang { SC_Register }; - /// Checks whether the given storage class is legal for functions. + /// \brief Checks whether the given storage class is legal for functions. inline bool isLegalForFunction(StorageClass SC) { return SC <= SC_PrivateExtern; } - /// Checks whether the given storage class is legal for variables. + /// \brief Checks whether the given storage class is legal for variables. inline bool isLegalForVariable(StorageClass SC) { return true; } diff --git a/clang/include/clang/Basic/TargetBuiltins.h b/clang/include/clang/Basic/TargetBuiltins.h index ea7e2ccc28dc..1d5004c37002 100644 --- a/clang/include/clang/Basic/TargetBuiltins.h +++ b/clang/include/clang/Basic/TargetBuiltins.h @@ -21,7 +21,7 @@ namespace clang { - /// ARM builtins + /// \brief ARM builtins namespace ARM { enum { LastTIBuiltin = clang::Builtin::FirstTSBuiltin-1, @@ -31,7 +31,7 @@ namespace clang { }; } - /// PPC builtins + /// \brief PPC builtins namespace PPC { enum { LastTIBuiltin = clang::Builtin::FirstTSBuiltin-1, @@ -41,7 +41,7 @@ namespace clang { }; } - /// NVPTX builtins + /// \brief NVPTX builtins namespace NVPTX { enum { LastTIBuiltin = clang::Builtin::FirstTSBuiltin-1, @@ -52,7 +52,7 @@ namespace clang { } - /// X86 builtins + /// \brief X86 builtins namespace X86 { enum { LastTIBuiltin = clang::Builtin::FirstTSBuiltin-1, @@ -62,9 +62,9 @@ namespace clang { }; } - /// NeonTypeFlags - Flags to identify the types for overloaded Neon - /// builtins. These must be kept in sync with the flags in - /// utils/TableGen/NeonEmitter.h. + /// \brief Flags to identify the types for overloaded Neon builtins. + /// + /// These must be kept in sync with the flags in utils/TableGen/NeonEmitter.h. class NeonTypeFlags { enum { EltTypeMask = 0xf, @@ -102,7 +102,7 @@ namespace clang { bool isQuad() const { return (Flags & QuadFlag) != 0; } }; - /// Hexagon builtins + /// \brief Hexagon builtins namespace Hexagon { enum { LastTIBuiltin = clang::Builtin::FirstTSBuiltin-1, @@ -112,7 +112,7 @@ namespace clang { }; } - /// Mips builtins + /// \brief MIPS builtins namespace Mips { enum { LastTIBuiltin = clang::Builtin::FirstTSBuiltin-1, diff --git a/clang/include/clang/Basic/TargetInfo.h b/clang/include/clang/Basic/TargetInfo.h index 83060ba46391..125496a3604a 100644 --- a/clang/include/clang/Basic/TargetInfo.h +++ b/clang/include/clang/Basic/TargetInfo.h @@ -42,7 +42,7 @@ class TargetOptions; namespace Builtin { struct Info; } -/// TargetCXXABI - The types of C++ ABIs for which we can generate code. +/// \brief The types of C++ ABIs for which we can generate code. enum TargetCXXABI { /// The generic ("Itanium") C++ ABI, documented at: /// http://www.codesourcery.com/public/cxx-abi/ @@ -58,7 +58,7 @@ enum TargetCXXABI { CXXABI_Microsoft }; -/// TargetInfo - This class exposes information about the current target. +/// \brief Exposes information about the current target. /// class TargetInfo : public RefCountedBase { llvm::Triple Triple; @@ -100,7 +100,7 @@ protected: TargetInfo(const std::string &T); public: - /// CreateTargetInfo - Construct a target for the given options. + /// \brief Construct a target for the given options. /// /// \param Opts - The options to use to initialize the target. The target may /// modify the options to canonicalize the target feature information to match @@ -129,8 +129,8 @@ public: LongDouble }; - /// BuiltinVaListKind - The different kinds of __builtin_va_list types - /// defined by the target implementation. + /// \brief The different kinds of __builtin_va_list types defined by + /// the target implementation. enum BuiltinVaListKind { /// typedef char* __builtin_va_list; CharPtrBuiltinVaList = 0, @@ -156,7 +156,8 @@ protected: IntType SizeType, IntMaxType, UIntMaxType, PtrDiffType, IntPtrType, WCharType, WIntType, Char16Type, Char32Type, Int64Type, SigAtomicType; - /// Flag whether the Objective-C built-in boolean type should be signed char. + /// \brief Whether Objective-C's built-in boolean type should be signed char. + /// /// Otherwise, when this flag is not set, the normal built-in boolean type is /// used. unsigned UseSignedCharForObjCBool : 1; @@ -168,10 +169,12 @@ protected: /// boundary. unsigned UseBitFieldTypeAlignment : 1; - /// Control whether zero length bitfields (e.g., int : 0;) force alignment of - /// the next bitfield. If the alignment of the zero length bitfield is - /// greater than the member that follows it, `bar', `bar' will be aligned as - /// the type of the zero-length bitfield. + /// \brief Whether zero length bitfields (e.g., int : 0;) force alignment of + /// the next bitfield. + /// + /// If the alignment of the zero length bitfield is greater than the member + /// that follows it, `bar', `bar' will be aligned as the type of the + /// zero-length bitfield. unsigned UseZeroLengthBitfieldAlignment : 1; /// If non-zero, specifies a fixed alignment value for bitfields that follow @@ -194,19 +197,20 @@ public: IntType getSigAtomicType() const { return SigAtomicType; } - /// getTypeWidth - Return the width (in bits) of the specified integer type - /// enum. For example, SignedInt -> getIntWidth(). + /// \brief Return the width (in bits) of the specified integer type enum. + /// + /// For example, SignedInt -> getIntWidth(). unsigned getTypeWidth(IntType T) const; - /// getTypeAlign - Return the alignment (in bits) of the specified integer - /// type enum. For example, SignedInt -> getIntAlign(). + /// \brief Return the alignment (in bits) of the specified integer type enum. + /// + /// For example, SignedInt -> getIntAlign(). unsigned getTypeAlign(IntType T) const; - /// isTypeSigned - Return whether an integer types is signed. Returns true if - /// the type is signed; false otherwise. + /// \brief Returns true if the type is signed; false otherwise. static bool isTypeSigned(IntType T); - /// getPointerWidth - Return the width of pointers on this target, for the + /// \brief Return the width of pointers on this target, for the /// specified address space. uint64_t getPointerWidth(unsigned AddrSpace) const { return AddrSpace == 0 ? PointerWidth : getPointerWidthV(AddrSpace); @@ -215,17 +219,21 @@ public: return AddrSpace == 0 ? PointerAlign : getPointerAlignV(AddrSpace); } - /// getBoolWidth/Align - Return the size of '_Bool' and C++ 'bool' for this - /// target, in bits. + /// \brief Return the size of '_Bool' and C++ 'bool' for this target, in bits. unsigned getBoolWidth() const { return BoolWidth; } + + /// \brief Return the alignment of '_Bool' and C++ 'bool' for this target. unsigned getBoolAlign() const { return BoolAlign; } unsigned getCharWidth() const { return 8; } // FIXME unsigned getCharAlign() const { return 8; } // FIXME - /// getShortWidth/Align - Return the size of 'signed short' and - /// 'unsigned short' for this target, in bits. + /// \brief Return the size of 'signed short' and 'unsigned short' for this + /// target, in bits. unsigned getShortWidth() const { return 16; } // FIXME + + /// \brief Return the alignment of 'signed short' and 'unsigned short' for + /// this target. unsigned getShortAlign() const { return 16; } // FIXME /// getIntWidth/Align - Return the size of 'signed int' and 'unsigned int' for @@ -243,7 +251,7 @@ public: unsigned getLongLongWidth() const { return LongLongWidth; } unsigned getLongLongAlign() const { return LongLongAlign; } - /// getSuitableAlign - Return the alignment that is suitable for storing any + /// \brief Return the alignment that is suitable for storing any /// object with a fundamental alignment requirement. unsigned getSuitableAlign() const { return SuitableAlign; } @@ -285,7 +293,7 @@ public: return *LongDoubleFormat; } - /// getFloatEvalMethod - Return the value for the C99 FLT_EVAL_METHOD macro. + /// \brief Return the value for the C99 FLT_EVAL_METHOD macro. virtual unsigned getFloatEvalMethod() const { return 0; } // getLargeArrayMinWidth/Align - Return the minimum array size that is @@ -293,21 +301,19 @@ public: unsigned getLargeArrayMinWidth() const { return LargeArrayMinWidth; } unsigned getLargeArrayAlign() const { return LargeArrayAlign; } - /// getMaxAtomicPromoteWidth - Return the maximum width lock-free atomic - /// operation which will ever be supported for the given target + /// \brief Return the maximum width lock-free atomic operation which will + /// ever be supported for the given target unsigned getMaxAtomicPromoteWidth() const { return MaxAtomicPromoteWidth; } - /// getMaxAtomicInlineWidth - Return the maximum width lock-free atomic - /// operation which can be inlined given the supported features of the - /// given target. + /// \brief Return the maximum width lock-free atomic operation which can be + /// inlined given the supported features of the given target. unsigned getMaxAtomicInlineWidth() const { return MaxAtomicInlineWidth; } - /// getIntMaxTWidth - Return the size of intmax_t and uintmax_t for this - /// target, in bits. + /// \brief Return the size of intmax_t and uintmax_t for this target, in bits. unsigned getIntMaxTWidth() const { return getTypeWidth(IntMaxType); } - /// getRegisterWidth - Return the "preferred" register width on this target. + /// \brief Return the "preferred" register width on this target. uint64_t getRegisterWidth() const { // Currently we assume the register width on the target matches the pointer // width, we can introduce a new variable for this if/when some target wants @@ -315,22 +321,24 @@ public: return LongWidth; } - /// getUserLabelPrefix - This returns the default value of the - /// __USER_LABEL_PREFIX__ macro, which is the prefix given to user symbols by - /// default. On most platforms this is "_", but it is "" on some, and "." on - /// others. + /// \brief Returns the default value of the __USER_LABEL_PREFIX__ macro, + /// which is the prefix given to user symbols by default. + /// + /// On most platforms this is "_", but it is "" on some, and "." on others. const char *getUserLabelPrefix() const { return UserLabelPrefix; } - /// MCountName - This returns name of the mcount instrumentation function. + /// \brief Returns the name of the mcount instrumentation function. const char *getMCountName() const { return MCountName; } - /// useSignedCharForObjCBool - Check if the Objective-C built-in boolean - /// type should be signed char. Otherwise, if this returns false, the - /// normal built-in boolean type should also be used for Objective-C. + /// \brief Check if the Objective-C built-in boolean type should be signed + /// char. + /// + /// Otherwise, if this returns false, the normal built-in boolean type + /// should also be used for Objective-C. bool useSignedCharForObjCBool() const { return UseSignedCharForObjCBool; } @@ -338,20 +346,20 @@ public: UseSignedCharForObjCBool = false; } - /// useBitFieldTypeAlignment() - Check whether the alignment of bit-field - /// types is respected when laying out structures. + /// \brief Check whether the alignment of bit-field types is respected + /// when laying out structures. bool useBitFieldTypeAlignment() const { return UseBitFieldTypeAlignment; } - /// useZeroLengthBitfieldAlignment() - Check whether zero length bitfields - /// should force alignment of the next member. + /// \brief Check whether zero length bitfields should force alignment of + /// the next member. bool useZeroLengthBitfieldAlignment() const { return UseZeroLengthBitfieldAlignment; } - /// getZeroLengthBitfieldBoundary() - Get the fixed alignment value in bits - /// for a member that follows a zero length bitfield. + /// \brief Get the fixed alignment value in bits for a member that follows + /// a zero length bitfield. unsigned getZeroLengthBitfieldBoundary() const { return ZeroLengthBitfieldBoundary; } @@ -361,22 +369,24 @@ public: return HasAlignMac68kSupport; } - /// getTypeName - Return the user string for the specified integer type enum. + /// \brief Return the user string for the specified integer type enum. + /// /// For example, SignedShort -> "short". static const char *getTypeName(IntType T); - /// getTypeConstantSuffix - Return the constant suffix for the specified - /// integer type enum. For example, SignedLong -> "L". + /// \brief Return the constant suffix for the specified integer type enum. + /// + /// For example, SignedLong -> "L". static const char *getTypeConstantSuffix(IntType T); /// \brief Check whether the given real type should use the "fpret" flavor of - /// Obj-C message passing on this target. + /// Objective-C message passing on this target. bool useObjCFPRetForRealType(RealType T) const { return RealTypeUsesObjCFPRet & (1 << T); } /// \brief Check whether _Complex long double should use the "fp2ret" flavor - /// of Obj-C message passing on this target. + /// of Objective-C message passing on this target. bool useObjCFP2RetForComplexLongDouble() const { return ComplexLongDoubleUsesFP2Ret; } @@ -389,35 +399,38 @@ public: MacroBuilder &Builder) const = 0; - /// getTargetBuiltins - Return information about target-specific builtins for + /// Return information about target-specific builtins for /// the current primary target, and info about which builtins are non-portable /// across the current set of primary and secondary targets. virtual void getTargetBuiltins(const Builtin::Info *&Records, unsigned &NumRecords) const = 0; - /// isCLZForZeroUndef - The __builtin_clz* and __builtin_ctz* built-in + /// The __builtin_clz* and __builtin_ctz* built-in /// functions are specified to have undefined results for zero inputs, but /// on targets that support these operations in a way that provides /// well-defined results for zero without loss of performance, it is a good /// idea to avoid optimizing based on that undef behavior. virtual bool isCLZForZeroUndef() const { return true; } - /// getBuiltinVaListKind - Returns the kind of __builtin_va_list - /// type that should be used with this target. + /// \brief Returns the kind of __builtin_va_list type that should be used + /// with this target. virtual BuiltinVaListKind getBuiltinVaListKind() const = 0; - /// isValidClobber - Returns whether the passed in string is - /// a valid clobber in an inline asm statement. This is used by - /// Sema. + /// \brief Returns whether the passed in string is a valid clobber in an + /// inline asm statement. + /// + /// This is used by Sema. bool isValidClobber(StringRef Name) const; - /// isValidGCCRegisterName - Returns whether the passed in string - /// is a valid register name according to GCC. This is used by Sema for - /// inline asm statements. + /// \brief Returns whether the passed in string is a valid register name + /// according to GCC. + /// + /// This is used by Sema for inline asm statements. bool isValidGCCRegisterName(StringRef Name) const; - // getNormalizedGCCRegisterName - Returns the "normalized" GCC register name. - // For example, on x86 it will return "ax" when "eax" is passed in. + /// \brief Returns the "normalized" GCC register name. + /// + /// For example, on x86 it will return "ax" when "eax" is passed in. StringRef getNormalizedGCCRegisterName(StringRef Name) const; struct ConstraintInfo { @@ -444,13 +457,15 @@ public: bool allowsRegister() const { return (Flags & CI_AllowsRegister) != 0; } bool allowsMemory() const { return (Flags & CI_AllowsMemory) != 0; } - /// hasMatchingInput - Return true if this output operand has a matching + /// \brief Return true if this output operand has a matching /// (tied) input operand. bool hasMatchingInput() const { return (Flags & CI_HasMatchingInput) != 0; } - /// hasTiedOperand() - Return true if this input operand is a matching - /// constraint that ties it to an output operand. If this returns true, - /// then getTiedOperand will indicate which output operand this is tied to. + /// \brief Return true if this input operand is a matching + /// constraint that ties it to an output operand. + /// + /// If this returns true then getTiedOperand will indicate which output + /// operand this is tied to. bool hasTiedOperand() const { return TiedOperand != -1; } unsigned getTiedOperand() const { assert(hasTiedOperand() && "Has no tied operand!"); @@ -462,9 +477,10 @@ public: void setAllowsRegister() { Flags |= CI_AllowsRegister; } void setHasMatchingInput() { Flags |= CI_HasMatchingInput; } - /// setTiedOperand - Indicate that this is an input operand that is tied to - /// the specified output operand. Copy over the various constraint - /// information from the output. + /// \brief Indicate that this is an input operand that is tied to + /// the specified output operand. + /// + /// Copy over the various constraint information from the output. void setTiedOperand(unsigned N, ConstraintInfo &Output) { Output.setHasMatchingInput(); Flags = Output.Flags; @@ -494,11 +510,11 @@ public: return std::string(1, *Constraint); } - // Returns a string of target-specific clobbers, in LLVM format. + /// \brief Returns a string of target-specific clobbers, in LLVM format. virtual const char *getClobbers() const = 0; - /// getTriple - Return the target triple of the primary target. + /// \brief Returns the target triple of the primary target. const llvm::Triple &getTriple() const { return Triple; } @@ -517,8 +533,7 @@ public: const unsigned RegNum; }; - /// hasProtectedVisibility - Does this target support "protected" - /// visibility? + /// \brief Does this target support "protected" visibility? /// /// Any target which dynamic libraries will naturally support /// something like "default" (meaning that the symbol is visible @@ -532,28 +547,29 @@ public: virtual bool useGlobalsForAutomaticVariables() const { return false; } - /// getCFStringSection - Return the section to use for CFString - /// literals, or 0 if no special section is used. + /// \brief Return the section to use for CFString literals, or 0 if no + /// special section is used. virtual const char *getCFStringSection() const { return "__DATA,__cfstring"; } - /// getNSStringSection - Return the section to use for NSString - /// literals, or 0 if no special section is used. + /// \brief Return the section to use for NSString literals, or 0 if no + /// special section is used. virtual const char *getNSStringSection() const { return "__OBJC,__cstring_object,regular,no_dead_strip"; } - /// getNSStringNonFragileABISection - Return the section to use for - /// NSString literals, or 0 if no special section is used (NonFragile ABI). + /// \brief Return the section to use for NSString literals, or 0 if no + /// special section is used (NonFragile ABI). virtual const char *getNSStringNonFragileABISection() const { return "__DATA, __objc_stringobj, regular, no_dead_strip"; } - /// isValidSectionSpecifier - This is an optional hook that targets can - /// implement to perform semantic checking on attribute((section("foo"))) - /// specifiers. In this case, "foo" is passed in to be checked. If the - /// section specifier is invalid, the backend should return a non-empty string + /// \brief An optional hook that targets can implement to perform semantic + /// checking on attribute((section("foo"))) specifiers. + /// + /// In this case, "foo" is passed in to be checked. If the section + /// specifier is invalid, the backend should return a non-empty string /// that indicates the problem. /// /// This hook is a simple quality of implementation feature to catch errors @@ -564,43 +580,44 @@ public: return ""; } - /// setForcedLangOptions - Set forced language options. + /// \brief Set forced language options. + /// /// Apply changes to the target information with respect to certain /// language options which change the target configuration. virtual void setForcedLangOptions(LangOptions &Opts); - /// getDefaultFeatures - Get the default set of target features for the CPU; + /// \brief Get the default set of target features for the CPU; /// this should include all legal feature strings on the target. virtual void getDefaultFeatures(llvm::StringMap &Features) const { } - /// getABI - Get the ABI in use. + /// \brief Get the ABI currently in use. virtual const char *getABI() const { return ""; } - /// getCXXABI - Get the C++ ABI in use. + /// \brief Get the C++ ABI currently in use. virtual TargetCXXABI getCXXABI() const { return CXXABI; } - /// setCPU - Target the specific CPU. + /// \brief Target the specified CPU. /// - /// \return - False on error (invalid CPU name). + /// \return False on error (invalid CPU name). virtual bool setCPU(const std::string &Name) { return false; } - /// setABI - Use the specific ABI. + /// \brief Use the specified ABI. /// - /// \return - False on error (invalid ABI name). + /// \return False on error (invalid ABI name). virtual bool setABI(const std::string &Name) { return false; } - /// setCXXABI - Use this specific C++ ABI. + /// \brief Use this specified C++ ABI. /// - /// \return - False on error (invalid C++ ABI name). + /// \return False on error (invalid C++ ABI name). bool setCXXABI(const std::string &Name) { static const TargetCXXABI Unknown = static_cast(-1); TargetCXXABI ABI = llvm::StringSwitch(Name) @@ -612,27 +629,28 @@ public: return setCXXABI(ABI); } - /// setCXXABI - Set the C++ ABI to be used by this implementation. + /// \brief Set the C++ ABI to be used by this implementation. /// - /// \return - False on error (ABI not valid on this target) + /// \return False on error (ABI not valid on this target) virtual bool setCXXABI(TargetCXXABI ABI) { CXXABI = ABI; return true; } - /// setFeatureEnabled - Enable or disable a specific target feature, + /// \brief Enable or disable a specific target feature; /// the feature name must be valid. /// - /// \return - False on error (invalid feature name). + /// \return False on error (invalid feature name). virtual bool setFeatureEnabled(llvm::StringMap &Features, StringRef Name, bool Enabled) const { return false; } - /// HandleTargetOptions - Perform initialization based on the user configured - /// set of features (e.g., +sse4). The list is guaranteed to have at most one - /// entry per feature. + /// \brief Perform initialization based on the user configured + /// set of features (e.g., +sse4). + /// + /// The list is guaranteed to have at most one entry per feature. /// /// The target may modify the features list, to change which options are /// passed onwards to the backend. @@ -644,19 +662,20 @@ public: return false; } - // getRegParmMax - Returns maximal number of args passed in registers. + // \brief Returns maximal number of args passed in registers. unsigned getRegParmMax() const { assert(RegParmMax < 7 && "RegParmMax value is larger than AST can handle"); return RegParmMax; } - /// isTLSSupported - Whether the target supports thread-local storage. + /// \brief Whether the target supports thread-local storage. bool isTLSSupported() const { return TLSSupported; } - /// hasNoAsmVariants - Return true if {|} are normal characters in the - /// asm string. If this returns false (the default), then {abc|xyz} is syntax + /// \brief Return true if {|} are normal characters in the asm string. + /// + /// If this returns false (the default), then {abc|xyz} is syntax /// that says that when compiling for asm variant #0, "abc" should be /// generated, but when compiling for asm variant #1, "xyz" should be /// generated. @@ -664,14 +683,13 @@ public: return NoAsmVariants; } - /// getEHDataRegisterNumber - Return the register number that - /// __builtin_eh_return_regno would return with the specified argument. + /// \brief Return the register number that __builtin_eh_return_regno would + /// return with the specified argument. virtual int getEHDataRegisterNumber(unsigned RegNo) const { return -1; } - /// getStaticInitSectionSpecifier - Return the section to use for C++ static - /// initialization functions. + /// \brief Return the section to use for C++ static initialization functions. virtual const char *getStaticInitSectionSpecifier() const { return 0; } diff --git a/clang/include/clang/Basic/TargetOptions.h b/clang/include/clang/Basic/TargetOptions.h index 19bfaff1f7c6..15ececd1df5d 100644 --- a/clang/include/clang/Basic/TargetOptions.h +++ b/clang/include/clang/Basic/TargetOptions.h @@ -20,7 +20,7 @@ namespace clang { -/// TargetOptions - Options for controlling the target. +/// \brief Options for controlling the target. class TargetOptions { public: /// If given, the name of the target triple to compile for. If not given the diff --git a/clang/include/clang/Basic/TokenKinds.h b/clang/include/clang/Basic/TokenKinds.h index ff3b1419b2bc..478add8db5db 100644 --- a/clang/include/clang/Basic/TokenKinds.h +++ b/clang/include/clang/Basic/TokenKinds.h @@ -19,24 +19,23 @@ namespace clang { namespace tok { -/// TokenKind - This provides a simple uniform namespace for tokens from all C -/// languages. +/// \brief Provides a simple uniform namespace for tokens from all C languages. enum TokenKind { #define TOK(X) X, #include "clang/Basic/TokenKinds.def" NUM_TOKENS }; -/// PPKeywordKind - This provides a namespace for preprocessor keywords which -/// start with a '#' at the beginning of the line. +/// \brief Provides a namespace for preprocessor keywords which start with a +/// '#' at the beginning of the line. enum PPKeywordKind { #define PPKEYWORD(X) pp_##X, #include "clang/Basic/TokenKinds.def" NUM_PP_KEYWORDS }; -/// ObjCKeywordKind - This provides a namespace for Objective-C keywords which -/// start with an '@'. +/// \brief Provides a namespace for Objective-C keywords which start with +/// an '@'. enum ObjCKeywordKind { #define OBJC1_AT_KEYWORD(X) objc_##X, #define OBJC2_AT_KEYWORD(X) objc_##X, @@ -44,8 +43,7 @@ enum ObjCKeywordKind { NUM_OBJC_KEYWORDS }; -/// OnOffSwitch - This defines the possible values of an on-off-switch -/// (C99 6.10.6p2). +/// \brief Defines the possible values of an on-off-switch (C99 6.10.6p2). enum OnOffSwitch { OOS_ON, OOS_OFF, OOS_DEFAULT }; diff --git a/clang/include/clang/Basic/TypeTraits.h b/clang/include/clang/Basic/TypeTraits.h index 4089e1a88cb8..0a5a8643a36e 100644 --- a/clang/include/clang/Basic/TypeTraits.h +++ b/clang/include/clang/Basic/TypeTraits.h @@ -17,7 +17,7 @@ namespace clang { - /// UnaryTypeTrait - Names for the unary type traits. + /// \brief Names for the unary type traits. enum UnaryTypeTrait { UTT_HasNothrowAssign, UTT_HasNothrowCopy, @@ -63,7 +63,7 @@ namespace clang { UTT_IsVolatile }; - /// BinaryTypeTrait - Names for the binary type traits. + /// \brief Names for the binary type traits. enum BinaryTypeTrait { BTT_IsBaseOf, BTT_IsConvertible, @@ -73,13 +73,13 @@ namespace clang { BTT_IsTriviallyAssignable }; - /// ArrayTypeTrait - Names for the array type traits. + /// \brief Names for the array type traits. enum ArrayTypeTrait { ATT_ArrayRank, ATT_ArrayExtent }; - /// UnaryExprOrTypeTrait - Names for the "expression or type" traits. + /// \brief Names for the "expression or type" traits. enum UnaryExprOrTypeTrait { UETT_SizeOf, UETT_AlignOf, diff --git a/clang/include/clang/Basic/Version.h b/clang/include/clang/Basic/Version.h index 101eb7a1fb75..3f1b4d83b95e 100644 --- a/clang/include/clang/Basic/Version.h +++ b/clang/include/clang/Basic/Version.h @@ -27,8 +27,7 @@ /// \brief Helper macro for CLANG_VERSION_STRING. #define CLANG_MAKE_VERSION_STRING(X,Y,Z) CLANG_MAKE_VERSION_STRING2(X.Y.Z) -/// \brief A string that describes the Clang version number, e.g., -/// "1.0". +/// \brief A string that describes the Clang version number, e.g., "1.0". #define CLANG_VERSION_STRING \ CLANG_MAKE_VERSION_STRING(CLANG_VERSION_MAJOR,CLANG_VERSION_MINOR, \ CLANG_VERSION_PATCHLEVEL) @@ -36,8 +35,7 @@ /// \brief Helper macro for CLANG_VERSION_STRING. #define CLANG_MAKE_VERSION_STRING(X,Y) CLANG_MAKE_VERSION_STRING2(X.Y) -/// \brief A string that describes the Clang version number, e.g., -/// "1.0". +/// \brief A string that describes the Clang version number, e.g., "1.0". #define CLANG_VERSION_STRING \ CLANG_MAKE_VERSION_STRING(CLANG_VERSION_MAJOR,CLANG_VERSION_MINOR) #endif @@ -48,31 +46,34 @@ namespace clang { /// Clang was built. std::string getClangRepositoryPath(); - /// \brief Retrieves the repository path from which LLVM was built. Supports - /// LLVM residing in a separate repository from clang. + /// \brief Retrieves the repository path from which LLVM was built. + /// + /// This supports LLVM residing in a separate repository from clang. std::string getLLVMRepositoryPath(); /// \brief Retrieves the repository revision number (or identifer) from which - /// this Clang was built. + /// this Clang was built. std::string getClangRevision(); /// \brief Retrieves the repository revision number (or identifer) from which - /// LLVM was built. If Clang and LLVM are in the same repository, this returns - /// the same string as getClangRevision. + /// LLVM was built. + /// + /// If Clang and LLVM are in the same repository, this returns the same + /// string as getClangRevision. std::string getLLVMRevision(); /// \brief Retrieves the full repository version that is an amalgamation of - /// the information in getClangRepositoryPath() and getClangRevision(). + /// the information in getClangRepositoryPath() and getClangRevision(). std::string getClangFullRepositoryVersion(); /// \brief Retrieves a string representing the complete clang version, - /// which includes the clang version number, the repository version, - /// and the vendor tag. + /// which includes the clang version number, the repository version, + /// and the vendor tag. std::string getClangFullVersion(); /// \brief Retrieves a string representing the complete clang version suitable - /// for use in the CPP __VERSION__ macro, which includes the clang version - /// number, the repository version, and the vendor tag. + /// for use in the CPP __VERSION__ macro, which includes the clang version + /// number, the repository version, and the vendor tag. std::string getClangFullCPPVersion(); } diff --git a/clang/include/clang/Basic/VersionTuple.h b/clang/include/clang/Basic/VersionTuple.h index 8a636d18a867..a94f76c182bb 100644 --- a/clang/include/clang/Basic/VersionTuple.h +++ b/clang/include/clang/Basic/VersionTuple.h @@ -74,15 +74,18 @@ public: return X.Major == Y.Major && X.Minor == Y.Minor && X.Subminor == Y.Subminor; } - /// \brief Determine if two version numbers are not equivalent. If - /// not provided, minor and subminor version numbers are considered to be + /// \brief Determine if two version numbers are not equivalent. + /// + /// If not provided, minor and subminor version numbers are considered to be /// zero. friend bool operator!=(const VersionTuple &X, const VersionTuple &Y) { return !(X == Y); } - /// \brief Determine whether one version number precedes another. If not - /// provided, minor and subminor version numbers are considered to be zero. + /// \brief Determine whether one version number precedes another. + /// + /// If not provided, minor and subminor version numbers are considered to be + /// zero. friend bool operator<(const VersionTuple &X, const VersionTuple &Y) { if (X.Major != Y.Major) return X.Major < Y.Major; @@ -93,31 +96,37 @@ public: return X.Subminor < Y.Subminor; } - /// \brief Determine whether one version number follows another. If not - /// provided, minor and subminor version numbers are considered to be zero. + /// \brief Determine whether one version number follows another. + /// + /// If not provided, minor and subminor version numbers are considered to be + /// zero. friend bool operator>(const VersionTuple &X, const VersionTuple &Y) { return Y < X; } /// \brief Determine whether one version number precedes or is - /// equivalent to another. If not provided, minor and subminor - /// version numbers are considered to be zero. + /// equivalent to another. + /// + /// If not provided, minor and subminor version numbers are considered to be + /// zero. friend bool operator<=(const VersionTuple &X, const VersionTuple &Y) { return !(Y < X); } /// \brief Determine whether one version number follows or is - /// equivalent to another. If not provided, minor and subminor - /// version numbers are considered to be zero. + /// equivalent to another. + /// + /// If not provided, minor and subminor version numbers are considered to be + /// zero. friend bool operator>=(const VersionTuple &X, const VersionTuple &Y) { return !(X < Y); } - /// \brief Retrieve a string representation of the version number/ + /// \brief Retrieve a string representation of the version number. std::string getAsString() const; /// \brief Try to parse the given string as a version number. - /// Returns true if the string does not match the regular expression + /// \returns \c true if the string does not match the regular expression /// [0-9]+(\.[0-9]+(\.[0-9]+)) bool tryParse(StringRef string); }; diff --git a/clang/include/clang/Basic/Visibility.h b/clang/include/clang/Basic/Visibility.h index 6285cb4b7be6..e81ad91a06c9 100644 --- a/clang/include/clang/Basic/Visibility.h +++ b/clang/include/clang/Basic/Visibility.h @@ -17,10 +17,12 @@ namespace clang { -/// Describes the different kinds of visibility that a -/// declaration may have. Visibility determines how a declaration -/// interacts with the dynamic linker. It may also affect whether the -/// symbol can be found by runtime symbol lookup APIs. +/// \brief Describes the different kinds of visibility that a declaration +/// may have. +/// +/// Visibility determines how a declaration interacts with the dynamic +/// linker. It may also affect whether the symbol can be found by runtime +/// symbol lookup APIs. /// /// Visibility is not described in any language standard and /// (nonetheless) sometimes has odd behavior. Not all platforms