Documentation cleanup: Add \file comment for ASTContest.h, add \brief to many

items, remove redundant names from doc comments, fix various typos, and tidy
up some wording.



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

1 files changed, 289 insertions, 253 deletions

diff --git a/include/clang/AST/ASTContext.h b/include/clang/AST/ASTContext.h
index a5c7012d34..299067dc24 100644
--- a/include/clang/AST/ASTContext.h
+++ b/include/clang/AST/ASTContext.h
@@ -6,9 +6,10 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-//  This file defines the ASTContext interface.
-//
+///
+/// \file
+/// \brief Defines the clang::ASTContext interface.
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_AST_ASTCONTEXT_H
@@ -84,8 +85,8 @@ namespace clang {
     class FullComment;
   }
 
-/// ASTContext - This class holds long-lived AST nodes (such as types and
-/// decls) that can be referred to throughout the semantic analysis of a file.
+/// \brief Holds long-lived AST nodes (such as types and decls) that can be
+/// referred to throughout the semantic analysis of a file.
 class ASTContext : public RefCountedBase<ASTContext> {
   ASTContext &this_() { return *this; }
 
@@ -144,19 +145,20 @@ class ASTContext : public RefCountedBase<ASTContext> {
   mutable NestedNameSpecifier *GlobalNestedNameSpecifier;
   friend class NestedNameSpecifier;
 
-  /// ASTRecordLayouts - A cache mapping from RecordDecls to ASTRecordLayouts.
-  ///  This is lazily created.  This is intentionally not serialized.
+  /// \brief A cache mapping from RecordDecls to ASTRecordLayouts.
+  ///
+  /// This is lazily created.  This is intentionally not serialized.
   mutable llvm::DenseMap<const RecordDecl*, const ASTRecordLayout*>
     ASTRecordLayouts;
   mutable llvm::DenseMap<const ObjCContainerDecl*, const ASTRecordLayout*>
     ObjCLayouts;
 
-  /// TypeInfoMap - A cache from types to size and alignment information.
+  /// \brief A cache from types to size and alignment information.
   typedef llvm::DenseMap<const Type*,
                          std::pair<uint64_t, unsigned> > TypeInfoMap;
   mutable TypeInfoMap MemoizedTypeInfo;
 
-  /// KeyFunctions - A cache mapping from CXXRecordDecls to key functions.
+  /// \brief A cache mapping from CXXRecordDecls to key functions.
   llvm::DenseMap<const CXXRecordDecl*, const CXXMethodDecl*> KeyFunctions;
   
   /// \brief Mapping from ObjCContainers to their ObjCImplementations.
@@ -170,7 +172,7 @@ class ASTContext : public RefCountedBase<ASTContext> {
   llvm::DenseMap<const VarDecl*, Expr*> BlockVarCopyInits;
     
   /// \brief Mapping from class scope functions specialization to their
-  ///  template patterns.
+  /// template patterns.
   llvm::DenseMap<const FunctionDecl*, FunctionDecl*>
     ClassScopeSpecializationPattern;
 
@@ -206,16 +208,16 @@ class ASTContext : public RefCountedBase<ASTContext> {
   /// __builtin_va_list type.
   mutable TypedefDecl *BuiltinVaListDecl;
 
-  /// \brief The typedef for the predefined 'id' type.
+  /// \brief The typedef for the predefined \c id type.
   mutable TypedefDecl *ObjCIdDecl;
   
-  /// \brief The typedef for the predefined 'SEL' type.
+  /// \brief The typedef for the predefined \c SEL type.
   mutable TypedefDecl *ObjCSelDecl;
 
-  /// \brief The typedef for the predefined 'Class' type.
+  /// \brief The typedef for the predefined \c Class type.
   mutable TypedefDecl *ObjCClassDecl;
 
-  /// \brief The typedef for the predefined 'Protocol' class in Objective-C.
+  /// \brief The typedef for the predefined \c Protocol class in Objective-C.
   mutable ObjCInterfaceDecl *ObjCProtocolClassDecl;
   
   /// \brief The typedef for the predefined 'BOOL' type.
@@ -299,9 +301,10 @@ class ASTContext : public RefCountedBase<ASTContext> {
     InstantiatedFromStaticDataMember;
 
   /// \brief Keeps track of the declaration from which a UsingDecl was
-  /// created during instantiation.  The source declaration is always
-  /// a UsingDecl, an UnresolvedUsingValueDecl, or an
-  /// UnresolvedUsingTypenameDecl.
+  /// created during instantiation.
+  ///
+  /// The source declaration is always a UsingDecl, an UnresolvedUsingValueDecl,
+  /// or an UnresolvedUsingTypenameDecl.
   ///
   /// For example:
   /// \code
@@ -340,9 +343,8 @@ class ASTContext : public RefCountedBase<ASTContext> {
   /// mangling context.
   llvm::DenseMap<const DeclContext *, LambdaMangleContext> LambdaMangleContexts;
   
-  /// \brief Mapping that stores parameterIndex values for ParmVarDecls
-  /// when that value exceeds the bitfield size of
-  /// ParmVarDeclBits.ParameterIndex.
+  /// \brief Mapping that stores parameterIndex values for ParmVarDecls when
+  /// that value exceeds the bitfield size of ParmVarDeclBits.ParameterIndex.
   typedef llvm::DenseMap<const VarDecl *, unsigned> ParameterIndexTable;
   ParameterIndexTable ParamIndices;  
   
@@ -351,10 +353,10 @@ class ASTContext : public RefCountedBase<ASTContext> {
   
   TranslationUnitDecl *TUDecl;
 
-  /// SourceMgr - The associated SourceManager object.
+  /// \brief The associated SourceManager object.a
   SourceManager &SourceMgr;
 
-  /// LangOpts - The language options used to create the AST associated with
+  /// \brief The language options used to create the AST associated with
   ///  this ASTContext object.
   LangOptions &LangOpts;
 
@@ -550,7 +552,7 @@ public:
                                            TemplateSpecializationKind TSK,
                         SourceLocation PointOfInstantiation = SourceLocation());
 
-  /// \brief If the given using decl is an instantiation of a
+  /// \brief If the given using decl \p Inst is an instantiation of a
   /// (possibly unresolved) using decl from a template instantiation,
   /// return it.
   NamedDecl *getInstantiatedFromUsingDecl(UsingDecl *Inst);
@@ -567,28 +569,28 @@ public:
 
   void setInstantiatedFromUnnamedFieldDecl(FieldDecl *Inst, FieldDecl *Tmpl);
   
-  /// ZeroBitfieldFollowsNonBitfield - return 'true" if 'FD' is a zero-length
-  /// bitfield which follows the non-bitfield 'LastFD'.
+  /// \brief Return \c true if \p FD is a zero-length bitfield which follows
+  /// the non-bitfield \p LastFD.
   bool ZeroBitfieldFollowsNonBitfield(const FieldDecl *FD, 
                                       const FieldDecl *LastFD) const;
 
-  /// ZeroBitfieldFollowsBitfield - return 'true" if 'FD' is a zero-length
-  /// bitfield which follows the bitfield 'LastFD'.
+  /// \brief Return \c true if \p FD is a zero-length bitfield which follows
+  /// the bitfield \p LastFD.
   bool ZeroBitfieldFollowsBitfield(const FieldDecl *FD,
                                    const FieldDecl *LastFD) const;
   
-  /// BitfieldFollowsBitfield - return 'true" if 'FD' is a
-  /// bitfield which follows the bitfield 'LastFD'.
+  /// \brief Return \c true if \p FD is a bitfield which follows the bitfield
+  /// \p LastFD.
   bool BitfieldFollowsBitfield(const FieldDecl *FD,
                                const FieldDecl *LastFD) const;
   
-  /// NonBitfieldFollowsBitfield - return 'true" if 'FD' is not a
-  /// bitfield which follows the bitfield 'LastFD'.
+  /// \brief Return \c true if \p FD is not a bitfield which follows the
+  /// bitfield \p LastFD.
   bool NonBitfieldFollowsBitfield(const FieldDecl *FD,
                                   const FieldDecl *LastFD) const;
   
-  /// BitfieldFollowsNonBitfield - return 'true" if 'FD' is a
-  /// bitfield which follows the none bitfield 'LastFD'.
+  /// \brief Return \c true if \p FD is a bitfield which follows the
+  /// non-bitfield \p LastFD.
   bool BitfieldFollowsNonBitfield(const FieldDecl *FD,
                                   const FieldDecl *LastFD) const;
 
@@ -735,77 +737,85 @@ public:
   //===--------------------------------------------------------------------===//
 
 private:
-  /// getExtQualType - Return a type with extended qualifiers.
+  /// \brief Return a type with extended qualifiers.
   QualType getExtQualType(const Type *Base, Qualifiers Quals) const;
 
   QualType getTypeDeclTypeSlow(const TypeDecl *Decl) const;
 
 public:
-  /// getAddSpaceQualType - Return the uniqued reference to the type for an
-  /// address space qualified type with the specified type and address space.
+  /// \brief Return the uniqued reference to the type for an address space
+  /// qualified type with the specified type and address space.
+  ///
   /// The resulting type has a union of the qualifiers from T and the address
   /// space. If T already has an address space specifier, it is silently
   /// replaced.
   QualType getAddrSpaceQualType(QualType T, unsigned AddressSpace) const;
 
-  /// getObjCGCQualType - Returns the uniqued reference to the type for an
-  /// objc gc qualified type. The retulting type has a union of the qualifiers
-  /// from T and the gc attribute.
+  /// \brief Return the uniqued reference to the type for an Objective-C
+  /// gc-qualified type.
+  ///
+  /// The retulting type has a union of the qualifiers from T and the gc
+  /// attribute.
   QualType getObjCGCQualType(QualType T, Qualifiers::GC gcAttr) const;
 
-  /// getRestrictType - Returns the uniqued reference to the type for a
-  /// 'restrict' qualified type.  The resulting type has a union of the
-  /// qualifiers from T and 'restrict'.
+  /// \brief Return the uniqued reference to the type for a \c restrict
+  /// qualified type.
+  ///
+  /// The resulting type has a union of the qualifiers from \p T and
+  /// \c restrict.
   QualType getRestrictType(QualType T) const {
     return T.withFastQualifiers(Qualifiers::Restrict);
   }
 
-  /// getVolatileType - Returns the uniqued reference to the type for a
-  /// 'volatile' qualified type.  The resulting type has a union of the
-  /// qualifiers from T and 'volatile'.
+  /// \brief Return the uniqued reference to the type for a \c volatile
+  /// qualified type.
+  ///
+  /// The resulting type has a union of the qualifiers from \p T and
+  /// \c volatile.
   QualType getVolatileType(QualType T) const {
     return T.withFastQualifiers(Qualifiers::Volatile);
   }
 
-  /// getConstType - Returns the uniqued reference to the type for a
-  /// 'const' qualified type.  The resulting type has a union of the
-  /// qualifiers from T and 'const'.
+  /// \brief Return the uniqued reference to the type for a \c const
+  /// qualified type.
+  ///
+  /// The resulting type has a union of the qualifiers from \p T and \c const.
   ///
-  /// It can be reasonably expected that this will always be
-  /// equivalent to calling T.withConst().
+  /// It can be reasonably expected that this will always be equivalent to
+  /// calling T.withConst().
   QualType getConstType(QualType T) const { return T.withConst(); }
 
-  /// adjustFunctionType - Change the ExtInfo on a function type.
+  /// \brief Change the ExtInfo on a function type.
   const FunctionType *adjustFunctionType(const FunctionType *Fn,
                                          FunctionType::ExtInfo EInfo);
 
-  /// getComplexType - Return the uniqued reference to the type for a complex
+  /// \brief Return the uniqued reference to the type for a complex
   /// number with the specified element type.
   QualType getComplexType(QualType T) const;
   CanQualType getComplexType(CanQualType T) const {
     return CanQualType::CreateUnsafe(getComplexType((QualType) T));
   }
 
-  /// getPointerType - Return the uniqued reference to the type for a pointer to
+  /// \brief Return the uniqued reference to the type for a pointer to
   /// the specified type.
   QualType getPointerType(QualType T) const;
   CanQualType getPointerType(CanQualType T) const {
     return CanQualType::CreateUnsafe(getPointerType((QualType) T));
   }
 
-  /// getAtomicType - Return the uniqued reference to the atomic type for
-  /// the specified type.
+  /// \brief Return the uniqued reference to the atomic type for the specified
+  /// type.
   QualType getAtomicType(QualType T) const;
 
-  /// getBlockPointerType - Return the uniqued reference to the type for a block
-  /// of the specified type.
+  /// \brief Return the uniqued reference to the type for a block of the
+  /// specified type.
   QualType getBlockPointerType(QualType T) const;
 
-  /// This gets the struct used to keep track of the descriptor for pointer to
+  /// Gets the struct used to keep track of the descriptor for pointer to
   /// blocks.
   QualType getBlockDescriptorType() const;
 
-  /// This gets the struct used to keep track of the extended descriptor for
+  /// Gets the struct used to keep track of the extended descriptor for
   /// pointer to blocks.
   QualType getBlockDescriptorExtendedType() const;
 
@@ -816,78 +826,82 @@ public:
     return cudaConfigureCallDecl;
   }
 
-  /// This builds the struct used for __block variables.
+  /// Builds the struct used for __block variables.
   QualType BuildByRefType(StringRef DeclName, QualType Ty) const;
 
   /// Returns true iff we need copy/dispose helpers for the given type.
   bool BlockRequiresCopying(QualType Ty) const;
 
-  /// getLValueReferenceType - Return the uniqued reference to the type for an
-  /// lvalue reference to the specified type.
+  /// \brief Return the uniqued reference to the type for an lvalue reference
+  /// to the specified type.
   QualType getLValueReferenceType(QualType T, bool SpelledAsLValue = true)
     const;
 
-  /// getRValueReferenceType - Return the uniqued reference to the type for an
-  /// rvalue reference to the specified type.
+  /// \brief Return the uniqued reference to the type for an rvalue reference
+  /// to the specified type.
   QualType getRValueReferenceType(QualType T) const;
 
-  /// getMemberPointerType - Return the uniqued reference to the type for a
-  /// member pointer to the specified type in the specified class. The class
-  /// is a Type because it could be a dependent name.
+  /// \brief Return the uniqued reference to the type for a member pointer to
+  /// the specified type in the specified class.
+  ///
+  /// The class \p Cls is a \c Type because it could be a dependent name.
   QualType getMemberPointerType(QualType T, const Type *Cls) const;
 
-  /// getVariableArrayType - Returns a non-unique reference to the type for a
-  /// variable array of the specified element type.
+  /// \brief Return a non-unique reference to the type for a variable array of
+  /// the specified element type.
   QualType getVariableArrayType(QualType EltTy, Expr *NumElts,
                                 ArrayType::ArraySizeModifier ASM,
                                 unsigned IndexTypeQuals,
                                 SourceRange Brackets) const;
 
-  /// getDependentSizedArrayType - Returns a non-unique reference to
-  /// the type for a dependently-sized array of the specified element
-  /// type. FIXME: We will need these to be uniqued, or at least
-  /// comparable, at some point.
+  /// \brief Return a non-unique reference to the type for a dependently-sized
+  /// array of the specified element type.
+  ///
+  /// FIXME: We will need these to be uniqued, or at least comparable, at some
+  /// point.
   QualType getDependentSizedArrayType(QualType EltTy, Expr *NumElts,
                                       ArrayType::ArraySizeModifier ASM,
                                       unsigned IndexTypeQuals,
                                       SourceRange Brackets) const;
 
-  /// getIncompleteArrayType - Returns a unique reference to the type for a
-  /// incomplete array of the specified element type.
+  /// \brief Return a unique reference to the type for an incomplete array of
+  /// the specified element type.
   QualType getIncompleteArrayType(QualType EltTy,
                                   ArrayType::ArraySizeModifier ASM,
                                   unsigned IndexTypeQuals) const;
 
-  /// getConstantArrayType - Return the unique reference to the type for a
-  /// constant array of the specified element type.
+  /// \brief Return the unique reference to the type for a constant array of
+  /// the specified element type.
   QualType getConstantArrayType(QualType EltTy, const llvm::APInt &ArySize,
                                 ArrayType::ArraySizeModifier ASM,
                                 unsigned IndexTypeQuals) const;
   
-  /// getVariableArrayDecayedType - Returns a vla type where known sizes
-  /// are replaced with [*].
+  /// \brief Returns a vla type where known sizes are replaced with [*].
   QualType getVariableArrayDecayedType(QualType Ty) const;
 
-  /// getVectorType - Return the unique reference to a vector type of
-  /// the specified element type and size. VectorType must be a built-in type.
+  /// \brief Return the unique reference to a vector type of the specified
+  /// element type and size.
+  ///
+  /// \pre \p VectorType must be a built-in type.
   QualType getVectorType(QualType VectorType, unsigned NumElts,
                          VectorType::VectorKind VecKind) const;
 
-  /// getExtVectorType - Return the unique reference to an extended vector type
-  /// of the specified element type and size.  VectorType must be a built-in
-  /// type.
+  /// \brief Return the unique reference to an extended vector type
+  /// of the specified element type and size.
+  ///
+  /// \pre \p VectorType must be a built-in type.
   QualType getExtVectorType(QualType VectorType, unsigned NumElts) const;
 
-  /// getDependentSizedExtVectorType - Returns a non-unique reference to
-  /// the type for a dependently-sized vector of the specified element
-  /// type. FIXME: We will need these to be uniqued, or at least
-  /// comparable, at some point.
+  /// \pre Return a non-unique reference to the type for a dependently-sized
+  /// vector of the specified element type.
+  ///
+  /// FIXME: We will need these to be uniqued, or at least comparable, at some
+  /// point.
   QualType getDependentSizedExtVectorType(QualType VectorType,
                                           Expr *SizeExpr,
                                           SourceLocation AttrLoc) const;
 
-  /// getFunctionNoProtoType - Return a K&R style C function type like 'int()'.
-  ///
+  /// \brief Return a K&R style C function type like 'int()'.
   QualType getFunctionNoProtoType(QualType ResultTy,
                                   const FunctionType::ExtInfo &Info) const;
 
@@ -895,14 +909,13 @@ public:
     return getFunctionNoProtoType(ResultTy, FunctionType::ExtInfo());
   }
 
-  /// getFunctionType - Return a normal function type with a typed
-  /// argument list.
+  /// \brief Return a normal function type with a typed argument list.
   QualType getFunctionType(QualType ResultTy,
                            const QualType *Args, unsigned NumArgs,
                            const FunctionProtoType::ExtProtoInfo &EPI) const;
 
-  /// getTypeDeclType - Return the unique reference to the type for
-  /// the specified type declaration.
+  /// \brief Return the unique reference to the type for the specified type
+  /// declaration.
   QualType getTypeDeclType(const TypeDecl *Decl,
                            const TypeDecl *PrevDecl = 0) const {
     assert(Decl && "Passed null for Decl param");
@@ -917,8 +930,8 @@ public:
     return getTypeDeclTypeSlow(Decl);
   }
 
-  /// getTypedefType - Return the unique reference to the type for the
-  /// specified typedef-name decl.
+  /// \brief Return the unique reference to the type for the specified
+  /// typedef-name decl.
   QualType getTypedefType(const TypedefNameDecl *Decl,
                           QualType Canon = QualType()) const;
 
@@ -990,69 +1003,71 @@ public:
                              ObjCProtocolDecl * const *Protocols,
                              unsigned NumProtocols) const;
 
-  /// getObjCObjectPointerType - Return a ObjCObjectPointerType type
-  /// for the given ObjCObjectType.
+  /// \brief Return a ObjCObjectPointerType type for the given ObjCObjectType.
   QualType getObjCObjectPointerType(QualType OIT) const;
 
-  /// getTypeOfType - GCC extension.
+  /// \brief GCC extension.
   QualType getTypeOfExprType(Expr *e) const;
   QualType getTypeOfType(QualType t) const;
 
-  /// getDecltypeType - C++0x decltype.
+  /// \brief C++11 decltype.
   QualType getDecltypeType(Expr *e, QualType UnderlyingType) const;
 
-  /// getUnaryTransformType - unary type transforms
+  /// \brief Unary type transforms
   QualType getUnaryTransformType(QualType BaseType, QualType UnderlyingType,
                                  UnaryTransformType::UTTKind UKind) const;
 
-  /// getAutoType - C++0x deduced auto type.
+  /// \brief C++11 deduced auto type.
   QualType getAutoType(QualType DeducedType) const;
 
-  /// getAutoDeductType - C++0x deduction pattern for 'auto' type.
+  /// \brief C++11 deduction pattern for 'auto' type.
   QualType getAutoDeductType() const;
 
-  /// getAutoRRefDeductType - C++0x deduction pattern for 'auto &&' type.
+  /// \brief C++11 deduction pattern for 'auto &&' type.
   QualType getAutoRRefDeductType() const;
 
-  /// getTagDeclType - Return the unique reference to the type for the
-  /// specified TagDecl (struct/union/class/enum) decl.
+  /// \brief Return the unique reference to the type for the specified TagDecl
+  /// (struct/union/class/enum) decl.
   QualType getTagDeclType(const TagDecl *Decl) const;
 
-  /// getSizeType - Return the unique type for "size_t" (C99 7.17), defined
-  /// in <stddef.h>. The sizeof operator requires this (C99 6.5.3.4p4).
+  /// \brief Return the unique type for "size_t" (C99 7.17), defined in
+  /// <stddef.h>.
+  ///
+  /// The sizeof operator requires this (C99 6.5.3.4p4).
   CanQualType getSizeType() const;
 
-  /// getIntMaxType - Return the unique type for "intmax_t" (C99 7.18.1.5),
-  /// defined in <stdint.h>.
+  /// \brief Return the unique type for "intmax_t" (C99 7.18.1.5), defined in
+  /// <stdint.h>.
   CanQualType getIntMaxType() const;
 
-  /// getUIntMaxType - Return the unique type for "uintmax_t" (C99 7.18.1.5),
-  /// defined in <stdint.h>.
+  /// \brief Return the unique type for "uintmax_t" (C99 7.18.1.5), defined in
+  /// <stdint.h>.
   CanQualType getUIntMaxType() const;
 
-  /// getWCharType - In C++, this returns the unique wchar_t type.  In C99, this
+  /// \brief In C++, this returns the unique wchar_t type.  In C99, this
   /// returns a type compatible with the type defined in <stddef.h> as defined
   /// by the target.
   QualType getWCharType() const { return WCharTy; }
 
-  /// getSignedWCharType - Return the type of "signed wchar_t".
+  /// \brief Return the type of "signed wchar_t".
+  ///
   /// Used when in C++, as a GCC extension.
   QualType getSignedWCharType() const;
 
-  /// getUnsignedWCharType - Return the type of "unsigned wchar_t".
+  /// \brief Return the type of "unsigned wchar_t".
+  ///
   /// Used when in C++, as a GCC extension.
   QualType getUnsignedWCharType() const;
 
-  /// getWIntType - In C99, this returns a type compatible with the type
+  /// \brief In C99, this returns a type compatible with the type
   /// defined in <stddef.h> as defined by the target.
   QualType getWIntType() const { return WIntTy; }
 
-  /// getPointerDiffType - Return the unique type for "ptrdiff_t" (C99 7.17)
-  /// defined in <stddef.h>. Pointer - pointer requires this (C99 6.5.6p9).
+  /// \brief Return the unique type for "ptrdiff_t" (C99 7.17) defined in
+  /// <stddef.h>. Pointer - pointer requires this (C99 6.5.6p9).
   QualType getPointerDiffType() const;
 
-  // getCFConstantStringType - Return the C structure type used to represent
-  // constant CFStrings.
+  /// \brief Return the C structure type used to represent constant CFStrings.
   QualType getCFConstantStringType() const;
 
   /// Get the structure type used to representation CFStrings, or NULL
@@ -1078,21 +1093,21 @@ public:
     ObjCNSStringType = T;
   }
   
-  /// \brief Retrieve the type that 'id' has been defined to, which may be
-  /// different from the built-in 'id' if 'id' has been typedef'd.
+  /// \brief Retrieve the type that \c id has been defined to, which may be
+  /// different from the built-in \c id if \c id has been typedef'd.
   QualType getObjCIdRedefinitionType() const {
     if (ObjCIdRedefinitionType.isNull())
       return getObjCIdType();
     return ObjCIdRedefinitionType;
   }
   
-  /// \brief Set the user-written type that redefines 'id'.
+  /// \brief Set the user-written type that redefines \c id.
   void setObjCIdRedefinitionType(QualType RedefType) {
     ObjCIdRedefinitionType = RedefType;
   }
 
-  /// \brief Retrieve the type that 'Class' has been defined to, which may be
-  /// different from the built-in 'Class' if 'Class' has been typedef'd.
+  /// \brief Retrieve the type that \c Class has been defined to, which may be
+  /// different from the built-in \c Class if \c Class has been typedef'd.
   QualType getObjCClassRedefinitionType() const {
     if (ObjCClassRedefinitionType.isNull())
       return getObjCClassType();
@@ -1179,27 +1194,29 @@ public:
     return getLangOpts().CPlusPlus ? BoolTy : IntTy;
   }
 
-  /// getObjCEncodingForType - Emit the ObjC type encoding for the
-  /// given type into \arg S. If \arg NameFields is specified then
-  /// record field names are also encoded.
-  void getObjCEncodingForType(QualType t, std::string &S,
+  /// \brief Emit the Objective-CC type encoding for the given type \p T into
+  /// \p S.
+  ///
+  /// If \p Field is specified then record field names are also encoded.
+  void getObjCEncodingForType(QualType T, std::string &S,
                               const FieldDecl *Field=0) const;
 
   void getLegacyIntegralTypeEncoding(QualType &t) const;
 
-  // Put the string version of type qualifiers into S.
+  /// \brief Put the string version of the type qualifiers \p QT into \p S.
   void getObjCEncodingForTypeQualifier(Decl::ObjCDeclQualifier QT,
                                        std::string &S) const;
 
-  /// getObjCEncodingForFunctionDecl - Returns the encoded type for this
-  /// function.  This is in the same format as Objective-C method encodings.  
+  /// \brief Emit the encoded type for the function \p Decl into \p S.
+  ///
+  /// This is in the same format as Objective-C method encodings.
   ///
   /// \returns true if an error occurred (e.g., because one of the parameter
   /// types is incomplete), false otherwise.
   bool getObjCEncodingForFunctionDecl(const FunctionDecl *Decl, std::string& S);
 
-  /// getObjCEncodingForMethodDecl - Return the encoded type for this method
-  /// declaration.
+  /// \brief Emit the encoded type for the method declaration \p Decl into
+  /// \p S.
   ///
   /// \returns true if an error occurred (e.g., because one of the parameter
   /// types is incomplete), false otherwise.
@@ -1207,8 +1224,7 @@ public:
                                     bool Extended = false)
     const;
 
-  /// getObjCEncodingForBlock - Return the encoded type for this block
-  /// declaration.
+  /// \brief Return the encoded type for this block declaration.
   std::string getObjCEncodingForBlock(const BlockExpr *blockExpr) const;
   
   /// getObjCEncodingForPropertyDecl - Return the encoded type for
@@ -1222,16 +1238,18 @@ public:
   bool ProtocolCompatibleWithProtocol(ObjCProtocolDecl *lProto,
                                       ObjCProtocolDecl *rProto) const;
 
-  /// getObjCEncodingTypeSize returns size of type for objective-c encoding
-  /// purpose in characters.
-  CharUnits getObjCEncodingTypeSize(QualType t) const;
+  /// \brief Return the size of type \p T for Objective-C encoding purpose,
+  /// in characters.
+  CharUnits getObjCEncodingTypeSize(QualType T) const;
 
-  /// \brief Retrieve the typedef corresponding to the predefined 'id' type
+  /// \brief Retrieve the typedef corresponding to the predefined \c id type
   /// in Objective-C.
   TypedefDecl *getObjCIdDecl() const;
   
-  /// This setter/getter represents the ObjC 'id' type. It is setup lazily, by
-  /// Sema.  id is always a (typedef for a) pointer type, a pointer to a struct.
+  /// \brief Represents the Objective-CC \c id type.
+  ///
+  /// This is set up lazily, by Sema.  \c id is always a (typedef for a)
+  /// pointer type, a pointer to a struct.
   QualType getObjCIdType() const {
     return getTypeDeclType(getObjCIdDecl());
   }
@@ -1250,15 +1268,16 @@ public:
   /// Objective-C 'Class' type.
   TypedefDecl *getObjCClassDecl() const;
   
-  /// This setter/getter repreents the ObjC 'Class' type. It is setup lazily, by
-  /// Sema.  'Class' is always a (typedef for a) pointer type, a pointer to a
-  /// struct.
+  /// \brief Represents the Objective-C \c Class type.
+  ///
+  /// This is set up lazily, by Sema.  \c Class is always a (typedef for a)
+  /// pointer type, a pointer to a struct.
   QualType getObjCClassType() const { 
     return getTypeDeclType(getObjCClassDecl());
   }
 
   /// \brief Retrieve the Objective-C class declaration corresponding to 
-  /// the predefined 'Protocol' class.
+  /// the predefined \c Protocol class.
   ObjCInterfaceDecl *getObjCProtocolDecl() const;
 
   /// \brief Retrieve declaration of 'BOOL' typedef
@@ -1276,37 +1295,37 @@ public:
     return getTypeDeclType(getBOOLDecl());
   }
   
-  /// \brief Retrieve the type of the Objective-C "Protocol" class.
+  /// \brief Retrieve the type of the Objective-C \c Protocol class.
   QualType getObjCProtoType() const {
     return getObjCInterfaceType(getObjCProtocolDecl());
   }
   
   /// \brief Retrieve the C type declaration corresponding to the predefined
-  /// __builtin_va_list type.
+  /// \c __builtin_va_list type.
   TypedefDecl *getBuiltinVaListDecl() const;
 
-  /// \brief Retrieve the type of the __builtin_va_list type.
+  /// \brief Retrieve the type of the \c __builtin_va_list type.
   QualType getBuiltinVaListType() const {
     return getTypeDeclType(getBuiltinVaListDecl());
   }
 
   /// \brief Retrieve the C type declaration corresponding to the predefined
-  /// __va_list_tag type used to help define the __builtin_va_list type for
-  /// some targets.
+  /// \c __va_list_tag type used to help define the \c __builtin_va_list type
+  /// for some targets.
   QualType getVaListTagType() const;
 
-  /// getCVRQualifiedType - Returns a type with additional const,
-  /// volatile, or restrict qualifiers.
+  /// \brief Return a type with additional \c const, \c volatile, or \crestrict
+  /// qualifiers.
   QualType getCVRQualifiedType(QualType T, unsigned CVR) const {
     return getQualifiedType(T, Qualifiers::fromCVRMask(CVR));
   }
 
-  /// getQualifiedType - Un-split a SplitQualType.
+  /// \brief Un-split a SplitQualType.
   QualType getQualifiedType(SplitQualType split) const {
     return getQualifiedType(split.Ty, split.Quals);
   }
 
-  /// getQualifiedType - Returns a type with additional qualifiers.
+  /// \brief Return a type with additional qualifiers.
   QualType getQualifiedType(QualType T, Qualifiers Qs) const {
     if (!Qs.hasNonFastQualifiers())
       return T.withFastQualifiers(Qs.getFastQualifiers());
@@ -1315,15 +1334,16 @@ public:
     return getExtQualType(Ptr, Qc);
   }
 
-  /// getQualifiedType - Returns a type with additional qualifiers.
+  /// \brief Return a type with additional qualifiers.
   QualType getQualifiedType(const Type *T, Qualifiers Qs) const {
     if (!Qs.hasNonFastQualifiers())
       return QualType(T, Qs.getFastQualifiers());
     return getExtQualType(T, Qs);
   }
 
-  /// getLifetimeQualifiedType - Returns a type with the given
-  /// lifetime qualifier.
+  /// \brief Return a type with the given lifetime qualifier.
+  ///
+  /// \pre Neither type.ObjCLifetime() nor \p lifetime may be \c OCL_None.
   QualType getLifetimeQualifiedType(QualType type,
                                     Qualifiers::ObjCLifetime lifetime) {
     assert(type.getObjCLifetime() == Qualifiers::OCL_None);
@@ -1360,8 +1380,9 @@ public:
     GE_Missing_ucontext   ///< Missing a type from <ucontext.h>
   };
 
-  /// GetBuiltinType - Return the type for the specified builtin.  If 
-  /// IntegerConstantArgs is non-null, it is filled in with a bitmask of
+  /// \brief Return the type for the specified builtin.
+  ///
+  /// If \p IntegerConstantArgs is non-null, it is filled in with a bitmask of
   /// arguments to the builtin that are required to be integer constant
   /// expressions.
   QualType GetBuiltinType(unsigned ID, GetBuiltinTypeError &Error,
@@ -1376,19 +1397,19 @@ private:
   //===--------------------------------------------------------------------===//
 
 public:
-  /// getObjCGCAttr - Returns one of GCNone, Weak or Strong objc's
-  /// garbage collection attribute.
-  ///
+  /// \brief Return one of the GCNone, Weak or Strong Objective-C garbage
+  /// collection attributes.
   Qualifiers::GC getObjCGCAttrKind(QualType Ty) const;
 
-  /// areCompatibleVectorTypes - Return true if the given vector types
-  /// are of the same unqualified type or if they are equivalent to the same
-  /// GCC vector type, ignoring whether they are target-specific (AltiVec or
-  /// Neon) types.
+  /// \brief Return true if the given vector types are of the same unqualified
+  /// type or if they are equivalent to the same GCC vector type.
+  ///
+  /// \note This ignores whether they are target-specific (AltiVec or Neon)
+  /// types.
   bool areCompatibleVectorTypes(QualType FirstVec, QualType SecondVec);
 
-  /// isObjCNSObjectType - Return true if this is an NSObject object with
-  /// its NSObject attribute set.
+  /// \brief Return true if this is an \c NSObject object with its \c NSObject
+  /// attribute set.
   static bool isObjCNSObjectType(QualType Ty) {
     return Ty->isObjCNSObjectType();
   }
@@ -1397,19 +1418,17 @@ public:
   //                         Type Sizing and Analysis
   //===--------------------------------------------------------------------===//
 
-  /// getFloatTypeSemantics - Return the APFloat 'semantics' for the specified
-  /// scalar floating point type.
+  /// \brief Return the APFloat 'semantics' for the specified scalar floating
+  /// point type.
   const llvm::fltSemantics &getFloatTypeSemantics(QualType T) const;
 
-  /// getTypeInfo - Get the size and alignment of the specified complete type in
-  /// bits.
+  /// \brief Get the size and alignment of the specified complete type in bits.
   std::pair<uint64_t, unsigned> getTypeInfo(const Type *T) const;
   std::pair<uint64_t, unsigned> getTypeInfo(QualType T) const {
     return getTypeInfo(T.getTypePtr());
   }
 
-  /// getTypeSize - Return the size of the specified type, in bits.  This method
-  /// does not work on incomplete types.
+  /// \brief Return the size of the specified (complete) type \p T, in bits.
   uint64_t getTypeSize(QualType T) const {
     return getTypeInfo(T).first;
   }
@@ -1417,24 +1436,24 @@ public:
     return getTypeInfo(T).first;
   }
 
-  /// getCharWidth - Return the size of the character type, in bits
+  /// \brief Return the size of the character type, in bits.
   uint64_t getCharWidth() const {
     return getTypeSize(CharTy);
   }
   
-  /// toCharUnitsFromBits - Convert a size in bits to a size in characters.
+  /// \brief Convert a size in bits to a size in characters.
   CharUnits toCharUnitsFromBits(int64_t BitSize) const;
 
-  /// toBits - Convert a size in characters to a size in bits.
+  /// \brief Convert a size in characters to a size in bits.
   int64_t toBits(CharUnits CharSize) const;
 
-  /// getTypeSizeInChars - Return the size of the specified type, in characters.
-  /// This method does not work on incomplete types.
+  /// \brief Return the size of the specified (complete) type \p T, in
+  /// characters.
   CharUnits getTypeSizeInChars(QualType T) const;
   CharUnits getTypeSizeInChars(const Type *T) const;
 
-  /// getTypeAlign - Return the ABI-specified alignment of a type, in bits.
-  /// This method does not work on incomplete types.
+  /// \brief Return the ABI-specified alignment of a (complete) type \p T, in
+  /// bits.
   unsigned getTypeAlign(QualType T) const {
     return getTypeInfo(T).second;
   }
@@ -1442,8 +1461,8 @@ public:
     return getTypeInfo(T).second;
   }
 
-  /// getTypeAlignInChars - Return the ABI-specified alignment of a type, in 
-  /// characters. This method does not work on incomplete types.
+  /// \brief Return the ABI-specified alignment of a (complete) type \p T, in 
+  /// characters.
   CharUnits getTypeAlignInChars(QualType T) const;
   CharUnits getTypeAlignInChars(const Type *T) const;
   
@@ -1454,41 +1473,47 @@ public:
   std::pair<CharUnits, CharUnits> getTypeInfoInChars(const Type *T) const;
   std::pair<CharUnits, CharUnits> getTypeInfoInChars(QualType T) const;
 
-  /// getPreferredTypeAlign - Return the "preferred" alignment of the specified
-  /// type for the current target in bits.  This can be different than the ABI
-  /// alignment in cases where it is beneficial for performance to overalign
-  /// a data type.
+  /// \brief Return the "preferred" alignment of the specified type \p T for
+  /// the current target, in bits.
+  ///
+  /// This can be different than the ABI alignment in cases where it is
+  /// beneficial for performance to overalign a data type.
   unsigned getPreferredTypeAlign(const Type *T) const;
 
-  /// getDeclAlign - Return a conservative estimate of the alignment of
-  /// the specified decl.  Note that bitfields do not have a valid alignment, so
-  /// this method will assert on them.
-  /// If @p RefAsPointee, references are treated like their underlying type
+  /// \brief Return a conservative estimate of the alignment of the specified
+  /// decl \p D.
+  ///
+  /// \pre \p D must not be a bitfield type, as bitfields do not have a valid
+  /// alignment.
+  ///
+  /// If \p RefAsPointee, references are treated like their underlying type
   /// (for alignof), else they're treated like pointers (for CodeGen).
   CharUnits getDeclAlign(const Decl *D, bool RefAsPointee = false) const;
 
-  /// getASTRecordLayout - Get or compute information about the layout of the
-  /// specified record (struct/union/class), which indicates its size and field
+  /// \brief Get or compute information about the layout of the specified
+  /// record (struct/union/class) \p D, which indicates its size and field
   /// position information.
   const ASTRecordLayout &getASTRecordLayout(const RecordDecl *D) const;
 
-  /// getASTObjCInterfaceLayout - Get or compute information about the
-  /// layout of the specified Objective-C interface.
+  /// \brief Get or compute information about the layout of the specified
+  /// Objective-C interface.
   const ASTRecordLayout &getASTObjCInterfaceLayout(const ObjCInterfaceDecl *D)
     const;
 
   void DumpRecordLayout(const RecordDecl *RD, raw_ostream &OS,
                         bool Simple = false) const;
 
-  /// getASTObjCImplementationLayout - Get or compute information about
-  /// the layout of the specified Objective-C implementation. This may
-  /// differ from the interface if synthesized ivars are present.
+  /// \brief Get or compute information about the layout of the specified
+  /// Objective-C implementation.
+  ///
+  /// This may differ from the interface if synthesized ivars are present.
   const ASTRecordLayout &
   getASTObjCImplementationLayout(const ObjCImplementationDecl *D) const;
 
-  /// getKeyFunction - Get the key function for the given record decl, or NULL
-  /// if there isn't one.  The key function is, according to the Itanium C++ ABI
-  /// section 5.2.3:
+  /// \brief Get the key fu