Documentation cleanup:
* Escaped # characters in Doxygen comments as needed;
* Added/reformatted \brief docs;
* Used a \file comment to document the file (MultipleIncludeOpt.h).


git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@158635 91177308-0d34-0410-b5e6-96231b3b80d8
diff --git a/include/clang/Lex/MultipleIncludeOpt.h b/include/clang/Lex/MultipleIncludeOpt.h
index 95b00df..e946e3c 100644
--- a/include/clang/Lex/MultipleIncludeOpt.h
+++ b/include/clang/Lex/MultipleIncludeOpt.h
@@ -6,10 +6,9 @@
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-//  This file defines the MultipleIncludeOpt interface.
-//
-//===----------------------------------------------------------------------===//
+
+/// \file
+/// \brief Defines the MultipleIncludeOpt interface.
 
 #ifndef LLVM_CLANG_MULTIPLEINCLUDEOPT_H
 #define LLVM_CLANG_MULTIPLEINCLUDEOPT_H
@@ -17,17 +16,18 @@
 namespace clang {
 class IdentifierInfo;
 
-/// MultipleIncludeOpt - This class implements the simple state machine that the
-/// Lexer class uses to detect files subject to the 'multiple-include'
-/// optimization.  The public methods in this class are triggered by various
+/// \brief Implements the simple state machine that the Lexer class uses to
+/// detect files subject to the 'multiple-include' optimization.
+///
+/// The public methods in this class are triggered by various
 /// events that occur when a file is lexed, and after the entire file is lexed,
 /// information about which macro (if any) controls the header is returned.
 class MultipleIncludeOpt {
   /// ReadAnyTokens - This is set to false when a file is first opened and true
   /// any time a token is returned to the client or a (non-multiple-include)
-  /// directive is parsed.  When the final #endif is parsed this is reset back
-  /// to false, that way any tokens before the first #ifdef or after the last
-  /// #endif can be easily detected.
+  /// directive is parsed.  When the final \#endif is parsed this is reset back
+  /// to false, that way any tokens before the first \#ifdef or after the last
+  /// \#endif can be easily detected.
   bool ReadAnyTokens;
 
   /// ReadAnyTokens - This is set to false when a file is first opened and true
@@ -56,7 +56,7 @@
     TheMacro = 0;
   }
 
-  /// getHasReadAnyTokensVal - This is used for the #ifndef hande-shake at the
+  /// getHasReadAnyTokensVal - This is used for the \#ifndef hande-shake at the
   /// top of the file when reading preprocessor directives.  Otherwise, reading
   /// the "ifndef x" would count as reading tokens.
   bool getHasReadAnyTokensVal() const { return ReadAnyTokens; }
@@ -68,14 +68,13 @@
   /// buffer, this method is called to disable the MIOpt if needed.
   void ExpandedMacro() { DidMacroExpansion = true; }
 
-  /// EnterTopLevelIFNDEF - When entering a top-level #ifndef directive (or the
-  /// "#if !defined" equivalent) without any preceding tokens, this method is
-  /// called.
+  /// \brief Called when entering a top-level \#ifndef directive (or the
+  /// "\#if !defined" equivalent) without any preceding tokens.
   ///
   /// Note, we don't care about the input value of 'ReadAnyTokens'.  The caller
   /// ensures that this is only called if there are no tokens read before the
-  /// #ifndef.  The caller is required to do this, because reading the #if line
-  /// obviously reads in in tokens.
+  /// \#ifndef.  The caller is required to do this, because reading the \#if
+  /// line obviously reads in in tokens.
   void EnterTopLevelIFNDEF(const IdentifierInfo *M) {
     // If the macro is already set, this is after the top-level #endif.
     if (TheMacro)
@@ -93,16 +92,14 @@
     TheMacro = M;
   }
 
-  /// EnterTopLevelConditional - This is invoked when a top level conditional
-  /// (except #ifndef) is found.
+  /// \brief Invoked when a top level conditional (except \#ifndef) is found.
   void EnterTopLevelConditional() {
     /// If a conditional directive (except #ifndef) is found at the top level,
     /// there is a chunk of the file not guarded by the controlling macro.
     Invalidate();
   }
 
-  /// ExitTopLevelConditional - This method is called when the lexer exits the
-  /// top-level conditional.
+  /// \brief Called when the lexer exits the top-level conditional.
   void ExitTopLevelConditional() {
     // If we have a macro, that means the top of the file was ok.  Set our state
     // back to "not having read any tokens" so we can detect anything after the
@@ -114,8 +111,8 @@
     ReadAnyTokens = false;
   }
 
-  /// GetControllingMacroAtEndOfFile - Once the entire file has been lexed, if
-  /// there is a controlling macro, return it.
+  /// \brief Once the entire file has been lexed, if there is a controlling
+  /// macro, return it.
   const IdentifierInfo *GetControllingMacroAtEndOfFile() const {
     // If we haven't read any tokens after the #endif, return the controlling
     // macro if it's valid (if it isn't, it will be null).