Documentation cleanup: Fixing \brief comments, migrating away from old style

that duplicated the name of the entity being documented at the start of its
comment, and other minor tidyups.

llvm-svn: 190655

clang/include/clang/Basic/IdentifierTable.h

@@ -148,7 +148,7 @@ public:
     return HadMacro;
   }
 
-  /// getTokenID - If this is a source-language token (e.g. 'for'), this API
+  /// If this is a source-language token (e.g. 'for'), this API
   /// can be used to cause the lexer to map identifiers to source-language
   /// tokens.
   tok::TokenKind getTokenID() const { return (tok::TokenKind)TokenID; }
@@ -184,8 +184,9 @@ public:
   }
   void setObjCKeywordID(tok::ObjCKeywordKind ID) { ObjCOrBuiltinID = ID; }
 
-  /// getBuiltinID - Return a value indicating whether this is a builtin
-  /// function.  0 is not-built-in.  1 is builtin-for-some-nonprimary-target.
+  /// \brief Return a value indicating whether this is a builtin function.
+  ///
+  /// 0 is not-built-in.  1 is builtin-for-some-nonprimary-target.
   /// 2+ are specific builtin functions.
   unsigned getBuiltinID() const {
     if (ObjCOrBuiltinID >= tok::NUM_OBJC_KEYWORDS)
@@ -237,7 +238,7 @@ public:
       RecomputeNeedsHandleIdentifier();
   }
 
-  /// isPoisoned - Return true if this token has been poisoned.
+  /// \brief Return true if this token has been poisoned.
   bool isPoisoned() const { return IsPoisoned; }
 
   /// isCPlusPlusOperatorKeyword/setIsCPlusPlusOperatorKeyword controls whether
@@ -257,12 +258,14 @@ public:
   T *getFETokenInfo() const { return static_cast<T*>(FETokenInfo); }
   void setFETokenInfo(void *T) { FETokenInfo = T; }
 
-  /// isHandleIdentifierCase - Return true if the Preprocessor::HandleIdentifier
-  /// must be called on a token of this identifier.  If this returns false, we
-  /// know that HandleIdentifier will not affect the token.
+  /// \brief Return true if the Preprocessor::HandleIdentifier must be called
+  /// on a token of this identifier.
+  ///
+  /// If this returns false, we know that HandleIdentifier will not affect
+  /// the token.
   bool isHandleIdentifierCase() const { return NeedsHandleIdentifier; }
 
-  /// isFromAST - Return true if the identifier in its current state was loaded
+  /// \brief Return true if the identifier in its current state was loaded
   /// from an AST file.
   bool isFromAST() const { return IsFromAST; }
 
@@ -294,12 +297,10 @@ public:
       RecomputeNeedsHandleIdentifier();
   }
   
-  /// \brief Determine whether this is the contextual keyword
-  /// 'import'.
+  /// \brief Determine whether this is the contextual keyword \c import.
   bool isModulesImport() const { return IsModulesImport; }
   
-  /// \brief Set whether this identifier is the contextual keyword 
-  /// 'import'.
+  /// \brief Set whether this identifier is the contextual keyword \c import.
   void setModulesImport(bool I) {
     IsModulesImport = I;
     if (I)
@@ -309,10 +310,9 @@ public:
   }
   
 private:
-  /// RecomputeNeedsHandleIdentifier - The Preprocessor::HandleIdentifier does
-  /// several special (but rare) things to identifiers of various sorts.  For
-  /// example, it changes the "for" keyword token from tok::identifier to
-  /// tok::for.
+  /// The Preprocessor::HandleIdentifier does several special (but rare)
+  /// things to identifiers of various sorts.  For example, it changes the
+  /// \c for keyword token from tok::identifier to tok::for.
   ///
   /// This method is very tied to the definition of HandleIdentifier.  Any
   /// change to it should be reflected here.
@@ -324,9 +324,10 @@ private:
   }
 };
 
-/// \brief an RAII object for [un]poisoning an identifier
-/// within a certain scope. II is allowed to be null, in
-/// which case, objects of this type have no effect.
+/// \brief An RAII object for [un]poisoning an identifier within a scope.
+///
+/// \p II is allowed to be null, in which case objects of this type have
+/// no effect.
 class PoisonIdentifierRAIIObject {
   IdentifierInfo *const II;
   const bool OldValue;
@@ -372,17 +373,16 @@ public:
   virtual StringRef Next() = 0;
 };
 
-/// IdentifierInfoLookup - An abstract class used by IdentifierTable that
-///  provides an interface for performing lookups from strings
-/// (const char *) to IdentiferInfo objects.
+/// \brief Provides lookups to, and iteration over, IdentiferInfo objects.
 class IdentifierInfoLookup {
 public:
   virtual ~IdentifierInfoLookup();
 
-  /// get - Return the identifier token info for the specified named identifier.
-  ///  Unlike the version in IdentifierTable, this returns a pointer instead
-  ///  of a reference.  If the pointer is NULL then the IdentifierInfo cannot
-  ///  be found.
+  /// \brief Return the IdentifierInfo for the specified named identifier.
+  ///
+  /// Unlike the version in IdentifierTable, this returns a pointer instead
+  /// of a reference.  If the pointer is null then the IdentifierInfo cannot
+  /// be found.
   virtual IdentifierInfo* get(StringRef Name) = 0;
 
   /// \brief Retrieve an iterator into the set of all identifiers