Ongoing documentation cleanup: fixed Doxygen markup errors, added \brief

annotations in many places where it involved little change, fixed some
examples and marked code examples with \code...\endcode, and changed a few
nearby mentions of C++0x to refer to C++11.

llvm-svn: 158486

clang/include/clang/AST/ASTContext.h

@@ -1705,7 +1705,7 @@ public:
   /// \brief Get the implementation of ObjCCategoryDecl, or NULL if none exists.
   ObjCCategoryImplDecl   *getObjCImplementation(ObjCCategoryDecl *D);
 
-  /// \brief returns true if there is at lease one \@implementation in TU.
+  /// \brief returns true if there is at least one \@implementation in TU.
   bool AnyObjCImplementation() {
     return !ObjCImpls.empty();
   }

clang/include/clang/AST/DeclCXX.h

@@ -98,7 +98,7 @@ namespace llvm {
 
 namespace clang {
 
-/// AccessSpecDecl - An access specifier followed by colon ':'.
+/// @brief Represents an access specifier followed by colon ':'.
 ///
 /// An objects of this class represents sugar for the syntactic occurrence
 /// of an access specifier followed by a colon in the list of member
@@ -110,7 +110,7 @@ namespace clang {
 /// "access declarations" (C++98 11.3 [class.access.dcl]).
 class AccessSpecDecl : public Decl {
   virtual void anchor();
-  /// ColonLoc - The location of the ':'.
+  /// \brief The location of the ':'.
   SourceLocation ColonLoc;
 
   AccessSpecDecl(AccessSpecifier AS, DeclContext *DC,
@@ -121,14 +121,14 @@ class AccessSpecDecl : public Decl {
   AccessSpecDecl(EmptyShell Empty)
     : Decl(AccessSpec, Empty) { }
 public:
-  /// getAccessSpecifierLoc - The location of the access specifier.
+  /// \brief The location of the access specifier.
   SourceLocation getAccessSpecifierLoc() const { return getLocation(); }
-  /// setAccessSpecifierLoc - Sets the location of the access specifier.
+  /// \brief Sets the location of the access specifier.
   void setAccessSpecifierLoc(SourceLocation ASLoc) { setLocation(ASLoc); }
 
-  /// getColonLoc - The location of the colon following the access specifier.
+  /// \brief The location of the colon following the access specifier.
   SourceLocation getColonLoc() const { return ColonLoc; }
-  /// setColonLoc - Sets the location of the colon.
+  /// \brief Sets the location of the colon.
   void setColonLoc(SourceLocation CLoc) { ColonLoc = CLoc; }
 
   SourceRange getSourceRange() const LLVM_READONLY {
@@ -149,7 +149,7 @@ public:
 };
 
 
-/// CXXBaseSpecifier - A base class of a C++ class.
+/// \brief Represents a base class of a C++ class.
 ///
 /// Each CXXBaseSpecifier represents a single, direct base class (or
 /// struct) of a C++ class (or struct). It specifies the type of that
@@ -175,7 +175,7 @@ class CXXBaseSpecifier {
   /// expansion.
   SourceLocation EllipsisLoc;
 
-  /// Virtual - Whether this is a virtual base class or not.
+  /// \brief Whether this is a virtual base class or not.
   bool Virtual : 1;
 
   /// BaseOfClass - Whether this is the base of a class (true) or of a
@@ -1179,12 +1179,12 @@ public:
   /// This routine will return non-NULL for (non-templated) member
   /// classes of class templates. For example, given:
   ///
-  /// \code
+  /// @code
   /// template<typename T>
   /// struct X {
   ///   struct A { };
   /// };
-  /// \endcode
+  /// @endcode
   ///
   /// The declaration for X<int>::A is a (non-templated) CXXRecordDecl
   /// whose parent is the class template specialization X<int>. For
@@ -1609,13 +1609,13 @@ public:
   ///
   /// In the following example, \c f() has an lvalue ref-qualifier, \c g()
   /// has an rvalue ref-qualifier, and \c h() has no ref-qualifier.
-  /// \code
+  /// @code
   /// struct X {
   ///   void f() &;
   ///   void g() &&;
   ///   void h();
   /// };
-  /// \endcode
+  /// @endcode
   RefQualifierKind getRefQualifier() const {
     return getType()->getAs<FunctionProtoType>()->getRefQualifier();
   }
@@ -2435,7 +2435,9 @@ public:
   friend class ASTDeclReader;
 };
 
-/// NamespaceAliasDecl - Represents a C++ namespace alias. For example:
+/// \brief Represents a C++ namespace alias.
+///
+/// For example:
 ///
 /// @code
 /// namespace Foo = Bar;
@@ -2522,17 +2524,19 @@ public:
   static bool classofKind(Kind K) { return K == NamespaceAlias; }
 };
 
-/// UsingShadowDecl - Represents a shadow declaration introduced into
+/// \brief Represents a shadow declaration introduced into a scope by a
-/// a scope by a (resolved) using declaration.  For example,
+/// (resolved) using declaration.
 ///
+/// For example,
+/// @code
 /// namespace A {
 ///   void foo();
 /// }
 /// namespace B {
-///   using A::foo(); // <- a UsingDecl
+///   using A::foo; // <- a UsingDecl
-///                   // Also creates a UsingShadowDecl for A::foo in B
+///                 // Also creates a UsingShadowDecl for A::foo() in B
 /// }
-///
+/// @endcode
 class UsingShadowDecl : public NamedDecl {
   virtual void anchor();
 
@@ -2594,8 +2598,12 @@ public:
   friend class ASTDeclWriter;
 };
 
-/// UsingDecl - Represents a C++ using-declaration. For example:
+/// \brief Represents a C++ using-declaration.
+///
+/// For example:
+/// @code
 ///    using someNameSpace::someIdentifier;
+/// @endcode
 class UsingDecl : public NamedDecl {
   virtual void anchor();
 
@@ -2610,8 +2618,10 @@ class UsingDecl : public NamedDecl {
   DeclarationNameLoc DNLoc;
 
   /// \brief The first shadow declaration of the shadow decl chain associated
-  /// with this using declaration. The bool member of the pair store whether
+  /// with this using declaration.
-  /// this decl has the 'typename' keyword.
+  ///
+  /// The bool member of the pair store whether this decl has the \c typename
+  /// keyword.
   llvm::PointerIntPair<UsingShadowDecl *, 1, bool> FirstUsingShadow;
 
   UsingDecl(DeclContext *DC, SourceLocation UL,
@@ -2720,14 +2730,17 @@ public:
   friend class ASTDeclWriter;
 };
 
-/// UnresolvedUsingValueDecl - Represents a dependent using
+/// \brief Represents a dependent using declaration which was not marked with
-/// declaration which was not marked with 'typename'.  Unlike
+/// \c typename.
-/// non-dependent using declarations, these *only* bring through
+///
+/// Unlike non-dependent using declarations, these *only* bring through
 /// non-types; otherwise they would break two-phase lookup.
 ///
-/// template <class T> class A : public Base<T> {
+/// @code
+/// template \<class T> class A : public Base<T> {
 ///   using Base<T>::foo;
 /// };
+/// @endcode
 class UnresolvedUsingValueDecl : public ValueDecl {
   virtual void anchor();
 
@@ -2791,14 +2804,16 @@ public:
   friend class ASTDeclWriter;
 };
 
-/// UnresolvedUsingTypenameDecl - Represents a dependent using
+/// @brief Represents a dependent using declaration which was marked with
-/// declaration which was marked with 'typename'.
+/// \c typename.
 ///
-/// template <class T> class A : public Base<T> {
+/// @code
+/// template \<class T> class A : public Base<T> {
 ///   using typename Base<T>::foo;
 /// };
+/// @endcode
 ///
-/// The type associated with a unresolved using typename decl is
+/// The type associated with an unresolved using typename decl is
 /// currently always a typename type.
 class UnresolvedUsingTypenameDecl : public TypeDecl {
   virtual void anchor();
@@ -2852,7 +2867,7 @@ public:
   static bool classofKind(Kind K) { return K == UnresolvedUsingTypename; }
 };
 
-/// StaticAssertDecl - Represents a C++0x static_assert declaration.
+/// \brief Represents a C++11 static_assert declaration.
 class StaticAssertDecl : public Decl {
   virtual void anchor();
   Expr *AssertExpr;
@@ -2892,7 +2907,7 @@ public:
   friend class ASTDeclReader;
 };
 
-/// Insertion operator for diagnostics.  This allows sending AccessSpecifier's
+/// Insertion operator for diagnostics.  This allows sending an AccessSpecifier
 /// into a diagnostic with <<.
 const DiagnosticBuilder &operator<<(const DiagnosticBuilder &DB,
                                     AccessSpecifier AS);

clang/include/clang/AST/DeclObjC.h

@@ -547,21 +547,25 @@ public:
   }
 };
 
-/// ObjCInterfaceDecl - Represents an ObjC class declaration. For example:
+/// \brief Represents an ObjC class declaration.
 ///
+/// For example:
+///
+/// \code
 ///   // MostPrimitive declares no super class (not particularly useful).
 ///   \@interface MostPrimitive
 ///     // no instance variables or methods.
 ///   \@end
 ///
 ///   // NSResponder inherits from NSObject & implements NSCoding (a protocol).
-///   \@interface NSResponder : NSObject <NSCoding>
+///   \@interface NSResponder : NSObject \<NSCoding>
 ///   { // instance variables are represented by ObjCIvarDecl.
 ///     id nextResponder; // nextResponder instance variable.
 ///   }
 ///   - (NSResponder *)nextResponder; // return a pointer to NSResponder.
 ///   - (void)mouseMoved:(NSEvent *)theEvent; // return void, takes a pointer
 ///   \@end                                    // to an NSEvent.
+/// \endcode
 ///
 ///   Unlike C/C++, forward class declarations are accomplished with \@class.
 ///   Unlike C/C++, \@class allows for a list of classes to be forward declared.
@@ -1065,8 +1069,7 @@ private:
 };
 
 
-/// ObjCAtDefsFieldDecl - Represents a field declaration created by an
+/// \brief Represents a field declaration created by an \@defs(...).
-/// \@defs(...).
 class ObjCAtDefsFieldDecl : public FieldDecl {
   virtual void anchor();
   ObjCAtDefsFieldDecl(DeclContext *DC, SourceLocation StartLoc,
@@ -1090,29 +1093,35 @@ public:
   static bool classofKind(Kind K) { return K == ObjCAtDefsField; }
 };
 
-/// ObjCProtocolDecl - Represents a protocol declaration. ObjC protocols
+/// \brief Represents an Objective-C protocol declaration.
-/// declare a pure abstract type (i.e no instance variables are permitted).
-/// Protocols originally drew inspiration from C++ pure virtual functions (a C++
-/// feature with nice semantics and lousy syntax:-). Here is an example:
 ///
+/// Objective-C protocols declare a pure abstract type (i.e., no instance
+/// variables are permitted).  Protocols originally drew inspiration from
+/// C++ pure virtual functions (a C++ feature with nice semantics and lousy
+/// syntax:-). Here is an example:
+///
+/// \code
 /// \@protocol NSDraggingInfo <refproto1, refproto2>
 /// - (NSWindow *)draggingDestinationWindow;
 /// - (NSImage *)draggedImage;
 /// \@end
+/// \endcode
 ///
 /// This says that NSDraggingInfo requires two methods and requires everything
 /// that the two "referenced protocols" 'refproto1' and 'refproto2' require as
 /// well.
 ///
-/// \@interface ImplementsNSDraggingInfo : NSObject <NSDraggingInfo>
+/// \code
+/// \@interface ImplementsNSDraggingInfo : NSObject \<NSDraggingInfo>
 /// \@end
+/// \endcode
 ///
 /// ObjC protocols inspired Java interfaces. Unlike Java, ObjC classes and
 /// protocols are in distinct namespaces. For example, Cocoa defines both
 /// an NSObject protocol and class (which isn't allowed in Java). As a result,
 /// protocols are referenced using angle brackets as follows:
 ///
-/// id <NSDraggingInfo> anyObjectThatImplementsNSDraggingInfo;
+/// id \<NSDraggingInfo> anyObjectThatImplementsNSDraggingInfo;
 ///
 class ObjCProtocolDecl : public ObjCContainerDecl,
                          public Redeclarable<ObjCProtocolDecl> {
@@ -1568,7 +1577,7 @@ class ObjCImplementationDecl : public ObjCImplDecl {
   /// true if class has a .cxx_[construct,destruct] method.
   bool HasCXXStructors : 1;
 
-  /// true of class extension has at least one bitfield ivar.
+  /// true if class extension has at least one bitfield ivar.
   bool HasSynthBitfield : 1;
 
   ObjCImplementationDecl(DeclContext *DC,
@@ -1725,10 +1734,12 @@ public:
 
 };
 
-/// ObjCPropertyDecl - Represents one property declaration in an interface.
+/// \brief Represents one property declaration in an Objective-C interface.
-/// For example:
-/// \@property (assign, readwrite) int MyProperty;
 ///
+/// For example:
+/// \code{.mm}
+/// \@property (assign, readwrite) int MyProperty;
+/// \endcode
 class ObjCPropertyDecl : public NamedDecl {
   virtual void anchor();
 public:

clang/include/clang/AST/EvaluatedExprVisitor.h

@@ -24,7 +24,7 @@ namespace clang {
   
 class ASTContext;
   
-/// \begin Given a potentially-evaluated expression, this visitor visits all
+/// \brief Given a potentially-evaluated expression, this visitor visits all
 /// of its potentially-evaluated subexpressions, recursively.
 template<typename ImplClass>
 class EvaluatedExprVisitor : public StmtVisitor<ImplClass> {

clang/include/clang/AST/Expr.h

@@ -225,7 +225,7 @@ public:
   /// recursively, any member or element of all contained aggregates or unions)
   /// with a const-qualified type.
   ///
-  /// \param Loc [in] [out] - A source location which *may* be filled
+  /// \param Loc [in,out] - A source location which *may* be filled
   /// in with the location of the expression making this a
   /// non-modifiable lvalue, if specified.
   enum isModifiableLvalueResult {
@@ -1385,8 +1385,8 @@ public:
     return StringRef(StrData.asChar, getByteLength());
   }
 
-  /// Allow clients that need the byte representation, such as ASTWriterStmt
+  /// Allow access to clients that need the byte representation, such as
-  /// ::VisitStringLiteral(), access.
+  /// ASTWriterStmt::VisitStringLiteral().
   StringRef getBytes() const {
     // FIXME: StringRef may not be the right type to use as a result for this.
     if (CharByteWidth == 1)

clang/include/clang/AST/ExprCXX.h

@@ -876,7 +876,7 @@ public:
   child_range children() { return child_range(&SubExpr, &SubExpr + 1); }
 };
 
-/// CXXConstructExpr - Represents a call to a C++ constructor.
+/// \brief Represents a call to a C++ constructor.
 class CXXConstructExpr : public Expr {
 public:
   enum ConstructionKind {
@@ -1015,9 +1015,13 @@ public:
   friend class ASTStmtReader;
 };
 
-/// CXXFunctionalCastExpr - Represents an explicit C++ type conversion
+/// \brief Represents an explicit C++ type conversion that uses "functional"
-/// that uses "functional" notion (C++ [expr.type.conv]). Example: @c
+/// notation (C++ [expr.type.conv]).
+///
+/// Example:
+/// @code
 ///   x = int(0.5);
+/// @endcode
 class CXXFunctionalCastExpr : public ExplicitCastExpr {
   SourceLocation TyBeginLoc;
   SourceLocation RParenLoc;
@@ -1436,15 +1440,16 @@ public:
   child_range children() { return child_range(); }
 };
 
-/// CXXNewExpr - A new expression for memory allocation and constructor calls,
+/// @brief Represents a new-expression for memory allocation and constructor
-/// e.g: "new CXXNewExpr(foo)".
+// calls, e.g: "new CXXNewExpr(foo)".
 class CXXNewExpr : public Expr {
   // Contains an optional array size expression, an optional initialization
   // expression, and any number of optional placement arguments, in that order.
   Stmt **SubExprs;
-  // Points to the allocation function used.
+  /// \brief Points to the allocation function used.
   FunctionDecl *OperatorNew;
-  // Points to the deallocation function used in case of error. May be null.
+  /// \brief Points to the deallocation function used in case of error. May be
+  /// null.
   FunctionDecl *OperatorDelete;
 
   /// \brief The allocated type-source information, as written in the source.
@@ -1624,8 +1629,8 @@ public:
   }
 };
 
-/// CXXDeleteExpr - A delete expression for memory deallocation and destructor
+/// \brief Represents a \c delete expression for memory deallocation and
-/// calls, e.g. "delete[] pArray".
+/// destructor calls, e.g. "delete[] pArray".
 class CXXDeleteExpr : public Expr {
   // Points to the operator delete overload that is used. Could be a member.
   FunctionDecl *OperatorDelete;
@@ -1695,8 +1700,7 @@ public:
   friend class ASTStmtReader;
 };
 
-/// \brief Structure used to store the type being destroyed by a
+/// \brief Stores the type being destroyed by a pseudo-destructor expression.
-/// pseudo-destructor expression.
 class PseudoDestructorTypeStorage {
   /// \brief Either the type source information or the name of the type, if
   /// it couldn't be resolved due to type-dependence.
@@ -1883,11 +1887,14 @@ public:
   child_range children() { return child_range(&Base, &Base + 1); }
 };
 
-/// UnaryTypeTraitExpr - A GCC or MS unary type trait, as used in the
+/// \brief Represents a GCC or MS unary type trait, as used in the
-/// implementation of TR1/C++0x type trait templates.
+/// implementation of TR1/C++11 type trait templates.
+///
 /// Example:
+/// @code
 ///   __is_pod(int) == true
 ///   __is_enum(std::string) == false
+/// @endcode
 class UnaryTypeTraitExpr : public Expr {
   /// UTT - The trait. A UnaryTypeTrait enum in MSVC compat unsigned.
   unsigned UTT : 31;
@@ -1938,10 +1945,13 @@ public:
   friend class ASTStmtReader;
 };
 
-/// BinaryTypeTraitExpr - A GCC or MS binary type trait, as used in the
+/// \brief Represents a GCC or MS binary type trait, as used in the
-/// implementation of TR1/C++0x type trait templates.
+/// implementation of TR1/C++11 type trait templates.
+///
 /// Example:
+/// @code
 ///   __is_base_of(Base, Derived) == true
+/// @endcode
 class BinaryTypeTraitExpr : public Expr {
   /// BTT - The trait. A BinaryTypeTrait enum in MSVC compat unsigned.
   unsigned BTT : 8;
@@ -2103,30 +2113,33 @@ public:
 
 };
   
-/// ArrayTypeTraitExpr - An Embarcadero array type trait, as used in the
+/// \brief An Embarcadero array type trait, as used in the implementation of
-/// implementation of __array_rank and __array_extent.
+/// __array_rank and __array_extent.
+///
 /// Example:
+/// @code
 ///   __array_rank(int[10][20]) == 2
 ///   __array_extent(int, 1)    == 20
+/// @endcode
 class ArrayTypeTraitExpr : public Expr {
   virtual void anchor();
 
-  /// ATT - The trait. An ArrayTypeTrait enum in MSVC compat unsigned.
+  /// \brief The trait. An ArrayTypeTrait enum in MSVC compat unsigned.
   unsigned ATT : 2;
 
-  /// The value of the type trait. Unspecified if dependent.
+  /// \brief The value of the type trait. Unspecified if dependent.
   uint64_t Value;
 
-  /// The array dimension being queried, or -1 if not used
+  /// \brief The array dimension being queried, or -1 if not used.
   Expr *Dimension;
 
-  /// Loc - The location of the type trait keyword.
+  /// \brief The location of the type trait keyword.
   SourceLocation Loc;
 
-  /// RParen - The location of the closing paren.
+  /// \brief The location of the closing paren.
   SourceLocation RParen;
 
-  /// The type being queried.
+  /// \brief The type being queried.
   TypeSourceInfo *QueriedType;
 
 public:
@@ -2173,22 +2186,26 @@ public:
   friend class ASTStmtReader;
 };
 
-/// ExpressionTraitExpr - An expression trait intrinsic
+/// \brief An expression trait intrinsic.
+///
 /// Example:
+/// @code
 ///   __is_lvalue_expr(std::cout) == true
 ///   __is_lvalue_expr(1) == false
+/// @endcode
 class ExpressionTraitExpr : public Expr {
-  /// ET - The trait. A ExpressionTrait enum in MSVC compat unsigned.
+  /// \brief The trait. A ExpressionTrait enum in MSVC compat unsigned.
   unsigned ET : 31;
-  /// The value of the type trait. Unspecified if dependent.
+  /// \brief The value of the type trait. Unspecified if dependent.
   bool Value : 1;
 
-  /// Loc - The location of the type trait keyword.
+  /// \brief The location of the type trait keyword.
   SourceLocation Loc;
 
-  /// RParen - The location of the closing paren.
+  /// \brief The location of the closing paren.
   SourceLocation RParen;
 
+  /// \brief The expression being queried.
   Expr* QueriedExpression;
 public:
   ExpressionTraitExpr(SourceLocation loc, ExpressionTrait et,
@@ -2207,7 +2224,9 @@ public:
     : Expr(ExpressionTraitExprClass, Empty), ET(0), Value(false),
       QueriedExpression() { }
 
-  SourceRange getSourceRange() const LLVM_READONLY { return SourceRange(Loc, RParen);}
+  SourceRange getSourceRange() const LLVM_READONLY {
+    return SourceRange(Loc, RParen);
+  }
 
   ExpressionTrait getTrait() const { return static_cast<ExpressionTrait>(ET); }
 
@@ -2230,7 +2249,7 @@ public:
 /// \brief A reference to an overloaded function set, either an
 /// \c UnresolvedLookupExpr or an \c UnresolvedMemberExpr.
 class OverloadExpr : public Expr {
-  /// The common name of these declarations.
+  /// \brief The common name of these declarations.
   DeclarationNameInfo NameInfo;
 
   /// \brief The nested-name-specifier that qualifies the name, if any.
@@ -2309,7 +2328,7 @@ public:
     return Result;
   }
 
-  /// Gets the naming class of this lookup, if any.
+  /// \brief Gets the naming class of this lookup, if any.
   CXXRecordDecl *getNamingClass() const;
 
   typedef UnresolvedSetImpl::iterator decls_iterator;
@@ -2318,25 +2337,25 @@ public:
     return UnresolvedSetIterator(Results + NumResults);
   }
 
-  /// Gets the number of declarations in the unresolved set.
+  /// \brief Gets the number of declarations in the unresolved set.
   unsigned getNumDecls() const { return NumResults; }
 
-  /// Gets the full name info.
+  /// \brief Gets the full name info.
   const DeclarationNameInfo &getNameInfo() const { return NameInfo; }
 
-  /// Gets the name looked up.
+  /// \brief Gets the name looked up.
   DeclarationName getName() const { return NameInfo.getName(); }
 
-  /// Gets the location of the name.
+  /// \brief Gets the location of the name.
   SourceLocation getNameLoc() const { return NameInfo.getLoc(); }
 
-  /// Fetches the nested-name qualifier, if one was given.
+  /// \brief Fetches the nested-name qualifier, if one was given.
   NestedNameSpecifier *getQualifier() const {
     return QualifierLoc.getNestedNameSpecifier();
   }
 
-  /// Fetches the nested-name qualifier with source-location information, if
+  /// \brief Fetches the nested-name qualifier with source-location
-  /// one was given.
+  /// information, if one was given.
   NestedNameSpecifierLoc getQualifierLoc() const { return QualifierLoc; }
 
   /// \brief Retrieve the location of the template keyword preceding
@@ -2360,10 +2379,10 @@ public:
     return getTemplateKWAndArgsInfo()->RAngleLoc;
   }
 
-  /// Determines whether the name was preceded by the template keyword.
+  /// \brief Determines whether the name was preceded by the template keyword.
   bool hasTemplateKeyword() const { return getTemplateKeywordLoc().isValid(); }
 
-  /// Determines whether this expression had explicit template arguments.
+  /// \brief Determines whether this expression had explicit template arguments.
   bool hasExplicitTemplateArgs() const { return getLAngleLoc().isValid(); }
 
   // Note that, inconsistently with the explicit-template-argument AST
@@ -2387,12 +2406,13 @@ public:
     return getExplicitTemplateArgs().NumTemplateArgs;
   }
 
-  /// Copies the template arguments into the given structure.
+  /// \brief Copies the template arguments into the given structure.
   void copyTemplateArgumentsInto(TemplateArgumentListInfo &List) const {
     getExplicitTemplateArgs().copyInto(List);
   }
 
   /// \brief Retrieves the optional explicit template arguments.
+  ///
   /// This points to the same data as getExplicitTemplateArgs(), but
   /// returns null if there are no explicit template arguments.
   const ASTTemplateArgumentListInfo *getOptionalExplicitTemplateArgs() {
@@ -2411,15 +2431,15 @@ public:
 };
 
 /// \brief A reference to a name which we were able to look up during
-/// parsing but could not resolve to a specific declaration.  This
+/// parsing but could not resolve to a specific declaration.
-/// arises in several ways:
+///
+/// This arises in several ways:
 ///   * we might be waiting for argument-dependent lookup
 ///   * the name might resolve to an overloaded function
 /// and eventually:
 ///   * the lookup might have included a function template
-/// These never include UnresolvedUsingValueDecls, which are always
+/// These never include UnresolvedUsingValueDecls, which are always class
-/// class members and therefore appear only in
+/// members and therefore appear only in UnresolvedMemberLookupExprs.
-/// UnresolvedMemberLookupExprs.
 class UnresolvedLookupExpr : public OverloadExpr {
   /// True if these lookup results should be extended by
   /// argument-dependent lookup if this is the operand of a function
@@ -2761,9 +2781,9 @@ public:
 /// type-dependent.
 ///
 /// The explicit type conversions expressed by
-/// CXXUnresolvedConstructExpr have the form \c T(a1, a2, ..., aN),
+/// CXXUnresolvedConstructExpr have the form <tt>T(a1, a2, ..., aN)<tt>,
-/// where \c T is some type and \c a1, a2, ..., aN are values, and
+/// where \c T is some type and \c a1, \c a2, ..., \c aN are values, and
-/// either \C T is a dependent type or one or more of the \c a's is
+/// either \c T is a dependent type or one or more of the <tt>a</tt>'s is
 /// type-dependent. For example, this would occur in a template such
 /// as:
 ///

clang/include/clang/AST/ExprObjC.h

@@ -90,7 +90,7 @@ public:
 /// ObjCBoxedExpr - used for generalized expression boxing.
 /// as in: @(strdup("hello world")) or @(random())
 /// Also used for boxing non-parenthesized numeric literals;
-/// as in: @42 or @true (c++/objc++) or @__yes (c/objc).
+/// as in: @42 or \@true (c++/objc++) or \@__yes (c/objc).
 class ObjCBoxedExpr : public Expr {
   Stmt *SubExpr;
   ObjCMethodDecl *BoxingMethod;
@@ -334,9 +334,9 @@ public:
 };
 
 
-/// ObjCEncodeExpr, used for @encode in Objective-C.  @encode has the same type
+/// ObjCEncodeExpr, used for \@encode in Objective-C.  \@encode has the same
-/// and behavior as StringLiteral except that the string initializer is obtained
+/// type and behavior as StringLiteral except that the string initializer is
-/// from ASTContext with the encoding type as an argument.
+/// obtained from ASTContext with the encoding type as an argument.
 class ObjCEncodeExpr : public Expr {
   TypeSourceInfo *EncodedType;
   SourceLocation AtLoc, RParenLoc;
@@ -1025,7 +1025,7 @@ public:
   /// a l-value or r-value reference will be an l-value or x-value,
   /// respectively.
   ///
-  /// \param LBrac The location of the open square bracket '['.
+  /// \param LBracLoc The location of the open square bracket '['.
   ///
   /// \param SuperLoc The location of the "super" keyword.
   ///
@@ -1039,8 +1039,6 @@ public:
   ///
   /// \param Args The message send arguments.
   ///
-  /// \param NumArgs The number of arguments.
-  ///
   /// \param RBracLoc The location of the closing square bracket ']'.
   static ObjCMessageExpr *Create(ASTContext &Context, QualType T, 
                                  ExprValueKind VK,
@@ -1065,7 +1063,7 @@ public:
   /// a l-value or r-value reference will be an l-value or x-value,
   /// respectively.
   ///
-  /// \param LBrac The location of the open square bracket '['.
+  /// \param LBracLoc The location of the open square bracket '['.
   ///
   /// \param Receiver The type of the receiver, including
   /// source-location information.
@@ -1077,8 +1075,6 @@ public:
   ///
   /// \param Args The message send arguments.
   ///
-  /// \param NumArgs The number of arguments.
-  ///
   /// \param RBracLoc The location of the closing square bracket ']'.
   static ObjCMessageExpr *Create(ASTContext &Context, QualType T,
                                  ExprValueKind VK,
@@ -1101,7 +1097,7 @@ public:
   /// a l-value or r-value reference will be an l-value or x-value,
   /// respectively.
   ///
-  /// \param LBrac The location of the open square bracket '['.
+  /// \param LBracLoc The location of the open square bracket '['.
   ///
   /// \param Receiver The expression used to produce the object that
   /// will receive this message.
@@ -1113,8 +1109,6 @@ public:
   ///
   /// \param Args The message send arguments.
   ///
-  /// \param NumArgs The number of arguments.
-  ///
   /// \param RBracLoc The location of the closing square bracket ']'.
   static ObjCMessageExpr *Create(ASTContext &Context, QualType T,
                                  ExprValueKind VK,

clang/include/clang/AST/StmtObjC.h

@@ -6,10 +6,9 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
+
-// This file defines the Objective-C statement AST node classes.
+/// \file
-//
+/// \brief Defines the Objective-C statement AST node classes.
-//===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_AST_STMTOBJC_H
 #define LLVM_CLANG_AST_STMTOBJC_H
@@ -19,9 +18,9 @@
 
 namespace clang {
 
-/// ObjCForCollectionStmt - This represents Objective-c's collection statement;
+/// \brief Represents Objective-C's collection statement.
-/// represented as 'for (element 'in' collection-expression)' stmt.
 ///
+/// This is represented as 'for (element 'in' collection-expression)' stmt.
 class ObjCForCollectionStmt : public Stmt {
   enum { ELEM, COLLECTION, BODY, END_EXPR };
   Stmt* SubExprs[END_EXPR]; // SubExprs[ELEM] is an expression or declstmt.
@@ -70,7 +69,7 @@ public:
   }
 };
 
-/// ObjCAtCatchStmt - This represents objective-c's \@catch statement.
+/// \brief Represents Objective-C's \@catch statement.
 class ObjCAtCatchStmt : public Stmt {
 private:
   VarDecl *ExceptionDecl;
@@ -118,7 +117,7 @@ public:
   child_range children() { return child_range(&Body, &Body + 1); }
 };
 
-/// ObjCAtFinallyStmt - This represent objective-c's \@finally Statement
+/// \brief Represents Objective-C's \@finally statement
 class ObjCAtFinallyStmt : public Stmt {
   Stmt *AtFinallyStmt;
   SourceLocation AtFinallyLoc;
@@ -151,24 +150,23 @@ public:
   }
 };
 
-/// ObjCAtTryStmt - This represent objective-c's over-all
+/// \brief Represents Objective-C's \@try ... \@catch ... \@finally statement.
-/// @try ... @catch ... @finally statement.
 class ObjCAtTryStmt : public Stmt {
 private:
-  // The location of the 
+  // The location of the @ in the \@try.
   SourceLocation AtTryLoc;
   
   // The number of catch blocks in this statement.
   unsigned NumCatchStmts : 16;
   
-  // Whether this statement has a @finally statement.
+  // Whether this statement has a \@finally statement.
   bool HasFinally : 1;
   
-  /// \brief Retrieve the statements that are stored after this @try statement.
+  /// \brief Retrieve the statements that are stored after this \@try statement.
   ///
   /// The order of the statements in memory follows the order in the source,
-  /// with the @try body first, followed by the @catch statements (if any) and,
+  /// with the \@try body first, followed by the \@catch statements (if any)
-  /// finally, the @finally (if it exists).
+  /// and, finally, the \@finally (if it exists).
   Stmt **getStmts() { return reinterpret_cast<Stmt **> (this + 1); }
   const Stmt* const *getStmts() const { 
     return reinterpret_cast<const Stmt * const*> (this + 1); 
@@ -223,7 +221,7 @@ public:
     getStmts()[I + 1] = S;
   }
   
-  /// Retrieve the \@finally statement, if any.
+  /// \brief Retrieve the \@finally statement, if any.
   const ObjCAtFinallyStmt *getFinallyStmt() const {
     if (!HasFinally)
       return 0;
@@ -254,11 +252,14 @@ public:
   }
 };
 
-/// ObjCAtSynchronizedStmt - This is for objective-c's @synchronized statement.
+/// \brief Represents Objective-C's \@synchronized statement.
-/// Example: @synchronized (sem) {
+///
+/// Example:
+/// \code
+///   @synchronized (sem) {
 ///     do-something;
 ///   }
-///
+/// \endcode
 class ObjCAtSynchronizedStmt : public Stmt {
 private:
   enum { SYNC_EXPR, SYNC_BODY, END_EXPR };
@@ -309,7 +310,7 @@ public:
   }
 };
 
-/// ObjCAtThrowStmt - This represents objective-c's @throw statement.
+/// \brief Represents Objective-C's \@throw statement.
 class ObjCAtThrowStmt : public Stmt {
   Stmt *Throw;
   SourceLocation AtThrowLoc;
@@ -343,8 +344,7 @@ public:
   child_range children() { return child_range(&Throw, &Throw+1); }
 };
 
-/// ObjCAutoreleasePoolStmt - This represent objective-c's 
+/// \brief Represents Objective-C's \@autoreleasepool Statement
-/// @autoreleasepool Statement
 class ObjCAutoreleasePoolStmt : public Stmt {
   Stmt *SubStmt;
   SourceLocation AtLoc;