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.


git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@159616 91177308-0d34-0410-b5e6-96231b3b80d8

29 files changed, 633 insertions, 531 deletions

diff --git a/include/clang/Basic/ABI.h b/include/clang/Basic/ABI.h
index 9599abe77a..fecf613a04 100644
--- a/include/clang/Basic/ABI.h
+++ b/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/include/clang/Basic/AddressSpaces.h b/include/clang/Basic/AddressSpaces.h
index b8077ec151..4b1cea50f8 100644
--- a/include/clang/Basic/AddressSpaces.h
+++ b/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/include/clang/Basic/AttrKinds.h b/include/clang/Basic/AttrKinds.h
index a429336e06..150a30e73d 100644
--- a/include/clang/Basic/AttrKinds.h
+++ b/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/include/clang/Basic/Builtins.h b/include/clang/Basic/Builtins.h
index aa6f9f9355..257daf10ec 100644
--- a/include/clang/Basic/Builtins.h
+++ b/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<const char *> &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/include/clang/Basic/Diagnostic.h b/include/clang/Basic/Diagnostic.h
index 361093b9d8..e46bbb6d1b 100644
--- a/include/clang/Basic/Diagnostic.h
+++ b/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<DiagnosticsEngine> {
 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<QualType, QualType>
+    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<QualType, QualType>
   };
 
-  /// 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<ArgumentKind, intptr_t> 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<DiagState> 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<DiagStatePoint> 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<const char*>(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<IdentifierInfo*>(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<char> &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<char> &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/include/clang/Basic/DiagnosticIDs.h b/include/clang/Basic/DiagnosticIDs.h
index 532de5ed06..3642da1197 100644
--- a/include/clang/Basic/DiagnosticIDs.h
+++ b/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<DiagnosticIDs> {
 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/include/clang/Basic/FileManager.h b/include/clang/Basic/FileManager.h
index 9017f4147d..deb9caf466 100644
--- a/include/clang/Basic/FileManager.h
+++ b/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<FileManager> {
   FileSystemOptions FileSystemOpts;
@@ -117,30 +118,37 @@ class FileManager : public RefCountedBase<FileManager> {
   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<DirectoryEntry*, 4> VirtualDirectoryEntries;
   /// \brief The virtual files that we have allocated.
   SmallVector<FileEntry*, 4> 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<DirectoryEntry*, llvm::BumpPtrAllocator> SeenDirEntries;
+
+  /// \brief A cache that maps paths to file entries (either real or
+  /// virtual) we have looked up.
+  ///
+  /// \see SeenDirEntries
   llvm::StringMap<FileEntry*, llvm::BumpPtrAllocator> 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/include/clang/Basic/FileSystemStatCache.h b/include/clang/Basic/FileSystemStatCache.h
index b39755b7c1..a802c7cc74 100644
--- a/include/clang/Basic/FileSystemStatCache.h
+++ b/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/include/clang/Basic/IdentifierTable.h b/include/clang/Basic/IdentifierTable.h
index f668e6ec4d..dc6acdaa91 100644
--- a/include/clang/Basic/IdentifierTable.h
+++ b/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<IdentifierInfo*, SourceLocation> 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<IdentifierInfo*> &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/include/clang/Basic/Lambda.h b/include/clang/Basic/Lambda.h
index 0014ed26e1..b1ad6acda3 100644
--- a/include/clang/Basic/Lambda.h
+++ b/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/include/clang/Basic/LangOptions.h b/include/clang/Basic/LangOptions.h
index 2edb556afe..10f496fd39 100644
--- a/include/clang/Basic/LangOptions.h
+++ b/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<LangOptions>, 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/include/clang/Basic/Linkage.h b/include/clang/Basic/Linkage.h
index 7922813ff8..6bc1f5d5ef 100644
--- a/include/clang/Basic/Linkage.h
+++ b/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/include/clang/Basic/ObjCRuntime.h b/include/clang/Basic/ObjCRuntime.h
index 13f13075fa..1be3b142c3 100644
--- a/include/clang/Basic/ObjCRuntime.h
+++ b/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/include/clang/Basic/OpenCL.h b/include/clang/Basic/OpenCL.h
index 5904a3fc15..3b3f259252 100644
--- a/include/clang/Basic/OpenCL.h
+++ b/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/include/clang/Basic/OperatorKinds.h b/include/clang/Basic/OperatorKinds.h
index 5900718644..108014faab 100644
--- a/include/clang/Basic/OperatorKinds.h
+++ b/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/include/clang/Basic/PartialDiagnostic.h b/include/clang/Basic/PartialDiagnostic.h
index 8e12a14a51..3f4626ec0a 100644
--- a/include/clang/Basic/PartialDiagnostic.h
+++ b/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<FixItHint, 6>  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/include/clang/Basic/PrettyStackTrace.h b/include/clang/Basic/PrettyStackTrace.h
index 2f8cba42f9..967d0d141e 100644
--- a/include/clang/Basic/PrettyStackTrace.h
+++ b/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/include/clang/Basic/SourceLocation.h b/include/clang/Basic/SourceLocation.h
index 453827ca2d..3bac26fbae 100644
--- a/include/clang/Basic/SourceLocation.h
+++ b/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<FileID, unsigned> 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/include/clang/Basic/SourceManager.h b/include/clang/Basic/SourceManager.h
index d5657c70e1..0cb3b834d7 100644
--- a/include/clang/Basic/SourceManager.h
+++ b/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<SourceManager> {
 
   /// \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<unsigned>(-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/include/clang/Basic/SourceManagerInternals.h b/include/clang/Basic/SourceManagerInternals.h
index 012c63d1ce..af95b78883 100644
--- a/include/clang/Basic/SourceManagerInternals.h
+++ b/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/include/clang/Basic/Specifiers.h b/include/clang/Basic/Specifiers.h
index ac81e56a8b..96cada1057 100644
--- a/include/clang/Basic/Specifiers.h
+++ b/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/include/clang/Basic/TargetBuiltins.h b/include/clang/Basic/TargetBuiltins.h
index ea7e2ccc28..1d5004c370 100644
--- a/include/clang/Basic/TargetBuiltins.h
+++ b/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/include/clang/Basic/TargetInfo.h b/include/clang/Basic/TargetInfo.h
index 83060ba463..125496a360 100644
--- a/include/clang/Basic/TargetInfo.h
+++ b/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<TargetInfo> {
   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<bool> &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<TargetCXXABI>(-1);
     TargetCXXABI ABI = llvm::StringSwitch<TargetCXXABI>(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<bool> &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/include/clang/Basic/TargetOptions.h b/include/clang/Basic/TargetOptions.h
index 19bfaff1f7..15ececd1df 100644
--- a/include/clang/Basic/TargetOptions.h
+++ b/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/include/clang/Basic/TokenKinds.h b/include/clang/Basic/TokenKinds.h
index ff3b1419b2..478add8db5 100644
--- a/include/clang/Basic/TokenKinds.h
+++ b/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/include/clang/Basic/TypeTraits.h b/include/clang/Basic/TypeTraits.h
index 4089e1a88c..0a5a8643a3 100644
--- a/include/clang/Basic/TypeTraits.h
+++ b/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/include/clang/Basic/Version.h b/include/clang/Basic/Version.h
index 101eb7a1fb..3f1b4d83b9 100644
--- a/include/clang/Basic/Version.h
+++ b/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/include/clang/Basic/VersionTuple.h b/include/clang/Basic/VersionTuple.h
index 8a636d18a8..a94f76c182 100644
--- a/include/clang/Basic/VersionTuple.h
+++ b/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/include/clang/Basic/Visibility.h b/include/clang/Basic/Visibility.h
index 6285cb4b7b..e81ad91a06 100644
--- a/include/clang/Basic/Visibility.h
+++ b/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