[cfe-commits] r158966 - /cfe/trunk/include/clang/Lex/Preprocessor.h

[James Dennett]

Author: jdennett
Date: Fri Jun 22 00:20:59 2012
New Revision: 158966

URL: http://llvm.org/viewvc/llvm-project?rev=158966&view=rev
Log:
Documentation cleanup:
* Escaped # and < characters in Doxygen comments as needed;
* Fixed up some \brief summaries;
* Marked up some parameter references with \p;
* Added \code...\endcode around code examples;
* Used \returns a little more.

Modified:
    cfe/trunk/include/clang/Lex/Preprocessor.h

Modified: cfe/trunk/include/clang/Lex/Preprocessor.h
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Lex/Preprocessor.h?rev=158966&r1=158965&r2=158966&view=diff
==============================================================================
--- cfe/trunk/include/clang/Lex/Preprocessor.h (original)
+++ cfe/trunk/include/clang/Lex/Preprocessor.h Fri Jun 22 00:20:59 2012
@@ -58,7 +58,7 @@
 /// Preprocessor - This object engages in a tight little dance with the lexer to
 /// efficiently preprocess tokens.  Lexers know only about tokens within a
 /// single source file, and don't know anything about preprocessor-level issues
-/// like the #include stack, token expansion, etc.
+/// like the \#include stack, token expansion, etc.
 ///
 class Preprocessor : public RefCountedBase<Preprocessor> {
   DiagnosticsEngine        *Diags;
@@ -103,7 +103,7 @@
   unsigned CounterValue;  // Next __COUNTER__ value.
 
   enum {
-    /// MaxIncludeStackDepth - Maximum depth of #includes.
+    /// MaxIncludeStackDepth - Maximum depth of \#includes.
     MaxAllowedIncludeStackDepth = 200
   };
 
@@ -175,11 +175,12 @@
   unsigned CodeCompletionOffset;
 
   /// \brief The location for the code-completion point. This gets instantiated
-  /// when the CodeCompletionFile gets #include'ed for preprocessing.
+  /// when the CodeCompletionFile gets \#include'ed for preprocessing.
   SourceLocation CodeCompletionLoc;
 
   /// \brief The start location for the file of the code-completion point.
-  /// This gets instantiated when the CodeCompletionFile gets #include'ed
+  ///
+  /// This gets instantiated when the CodeCompletionFile gets \#include'ed
   /// for preprocessing.
   SourceLocation CodeCompletionFileLoc;
 
@@ -225,7 +226,7 @@
 
   /// CurLookup - The DirectoryLookup structure used to find the current
   /// FileEntry, if CurLexer is non-null and if applicable.  This allows us to
-  /// implement #include_next and find directory-specific properties.
+  /// implement \#include_next and find directory-specific properties.
   const DirectoryLookup *CurDirLookup;
 
   /// CurTokenLexer - This is the current macro we are expanding, if we are
@@ -242,7 +243,7 @@
   } CurLexerKind;
 
   /// IncludeMacroStack - This keeps track of the stack of files currently
-  /// #included, and macros currently being expanded from, not counting
+  /// \#included, and macros currently being expanded from, not counting
   /// CurLexer/CurTokenLexer.
   struct IncludeStackInfo {
     enum CurLexerKind     CurLexerKind;
@@ -261,7 +262,7 @@
   std::vector<IncludeStackInfo> IncludeMacroStack;
 
   /// Callbacks - These are actions invoked when some preprocessor activity is
-  /// encountered (e.g. a file is #included, etc).
+  /// encountered (e.g. a file is \#included, etc).
   PPCallbacks *Callbacks;
 
   struct MacroExpandsInfo {
@@ -456,8 +457,8 @@
     Callbacks = C;
   }
 
-  /// getMacroInfo - Given an identifier, return the MacroInfo it is #defined to
-  /// or null if it isn't #define'd.
+  /// \brief Given an identifier, return the MacroInfo it is \#defined to
+  /// or null if it isn't \#define'd.
   MacroInfo *getMacroInfo(IdentifierInfo *II) const {
     if (!II->hasMacroDefinition())
       return 0;
@@ -465,8 +466,7 @@
     return getInfoForMacro(II);
   }
 
-  /// setMacroInfo - Specify a macro for this identifier.
-  ///
+  /// \brief Specify a macro for this identifier.
   void setMacroInfo(IdentifierInfo *II, MacroInfo *MI,
                     bool LoadedFromAST = false);
 
@@ -1062,24 +1062,27 @@
   /// \brief Retrieves the module that we're currently building, if any.
   Module *getCurrentModule();
   
-  /// AllocateMacroInfo - Allocate a new MacroInfo object with the provide
-  ///  SourceLocation.
+  /// \brief Allocate a new MacroInfo object with the provided SourceLocation.
   MacroInfo *AllocateMacroInfo(SourceLocation L);
 
-  /// CloneMacroInfo - Allocate a new MacroInfo object which is clone of MI.
+  /// \brief Allocate a new MacroInfo object which is clone of \p MI.
   MacroInfo *CloneMacroInfo(const MacroInfo &MI);
 
-  /// GetIncludeFilenameSpelling - Turn the specified lexer token into a fully
-  /// checked and spelled filename, e.g. as an operand of #include. This returns
-  /// true if the input filename was in <>'s or false if it were in ""'s.  The
-  /// caller is expected to provide a buffer that is large enough to hold the
-  /// spelling of the filename, but is also expected to handle the case when
-  /// this method decides to use a different buffer.
+  /// \brief Turn the specified lexer token into a fully checked and spelled
+  /// filename, e.g. as an operand of \#include. 
+  ///
+  /// The caller is expected to provide a buffer that is large enough to hold
+  /// the spelling of the filename, but is also expected to handle the case
+  /// when this method decides to use a different buffer.
+  ///
+  /// \returns true if the input filename was in <>'s or false if it was
+  /// in ""'s.
   bool GetIncludeFilenameSpelling(SourceLocation Loc,StringRef &Filename);
 
-  /// LookupFile - Given a "foo" or <foo> reference, look up the indicated file,
-  /// return null on failure.  isAngled indicates whether the file reference is
-  /// for system #include's or not (i.e. using <> instead of "").
+  /// \brief Given a "foo" or \<foo> reference, look up the indicated file.
+  ///
+  /// Returns null on failure.  \p isAngled indicates whether the file
+  /// reference is for system \#include's or not (i.e. using <> instead of "").
   const FileEntry *LookupFile(StringRef Filename,
                               bool isAngled, const DirectoryLookup *FromDir,
                               const DirectoryLookup *&CurDir,
@@ -1090,18 +1093,19 @@
 
   /// GetCurLookup - The DirectoryLookup structure used to find the current
   /// FileEntry, if CurLexer is non-null and if applicable.  This allows us to
-  /// implement #include_next and find directory-specific properties.
+  /// implement \#include_next and find directory-specific properties.
   const DirectoryLookup *GetCurDirLookup() { return CurDirLookup; }
 
-  /// isInPrimaryFile - Return true if we're in the top-level file, not in a
-  /// #include.
+  /// \brief Return true if we're in the top-level file, not in a \#include.
   bool isInPrimaryFile() const;
 
-  /// ConcatenateIncludeName - Handle cases where the #include name is expanded
+  /// ConcatenateIncludeName - Handle cases where the \#include name is expanded
   /// from a macro as multiple tokens, which need to be glued together.  This
   /// occurs for code like:
-  ///    #define FOO <a/b.h>
-  ///    #include FOO
+  /// \code
+  ///    \#define FOO <a/b.h>
+  ///    \#include FOO
+  /// \endcode
   /// because in this case, "<a/b.h>" is returned as 7 tokens, not one.
   ///
   /// This code concatenates and consumes tokens up to the '>' token.  It
@@ -1136,15 +1140,16 @@
     IncludeMacroStack.pop_back();
   }
 
-  /// AllocateMacroInfo - Allocate a new MacroInfo object.
+  /// \brief Allocate a new MacroInfo object.
   MacroInfo *AllocateMacroInfo();
 
-  /// ReleaseMacroInfo - Release the specified MacroInfo.  This memory will
-  ///  be reused for allocating new MacroInfo objects.
+  /// \brief Release the specified MacroInfo for re-use.
+  ///
+  /// This memory will  be reused for allocating new MacroInfo objects.
   void ReleaseMacroInfo(MacroInfo* MI);
 
   /// ReadMacroName - Lex and validate a macro name, which occurs after a
-  /// #define or #undef.  This emits a diagnostic, sets the token kind to eod,
+  /// \#define or \#undef.  This emits a diagnostic, sets the token kind to eod,
   /// and discards the rest of the macro line if the macro name is invalid.
   void ReadMacroName(Token &MacroNameTok, char isDefineUndef = 0);
 
@@ -1155,20 +1160,19 @@
   /// Return true if an error occurs parsing the arg list.
   bool ReadMacroDefinitionArgList(MacroInfo *MI, Token& LastTok);
 
-  /// SkipExcludedConditionalBlock - We just read a #if or related directive and
-  /// decided that the subsequent tokens are in the #if'd out portion of the
-  /// file.  Lex the rest of the file, until we see an #endif.  If
+  /// We just read a \#if or related directive and decided that the
+  /// subsequent tokens are in the \#if'd out portion of the
+  /// file.  Lex the rest of the file, until we see an \#endif.  If \p
   /// FoundNonSkipPortion is true, then we have already emitted code for part of
-  /// this #if directive, so #else/#elif blocks should never be entered. If
-  /// FoundElse is false, then #else directives are ok, if not, then we have
-  /// already seen one so a #else directive is a duplicate.  When this returns,
+  /// this \#if directive, so \#else/\#elif blocks should never be entered. If
+  /// \p FoundElse is false, then \#else directives are ok, if not, then we have
+  /// already seen one so a \#else directive is a duplicate.  When this returns,
   /// the caller can lex the first valid token.
   void SkipExcludedConditionalBlock(SourceLocation IfTokenLoc,
                                     bool FoundNonSkipPortion, bool FoundElse,
                                     SourceLocation ElseLoc = SourceLocation());
 
-  /// PTHSkipExcludedConditionalBlock - A fast PTH version of
-  ///  SkipExcludedConditionalBlock.
+  /// \brief A fast PTH version of SkipExcludedConditionalBlock.
   void PTHSkipExcludedConditionalBlock();
 
   /// EvaluateDirectiveExpression - Evaluate an integer constant expression that
@@ -1177,11 +1181,10 @@
   bool EvaluateDirectiveExpression(IdentifierInfo *&IfNDefMacro);
 
   /// RegisterBuiltinPragmas - Install the standard preprocessor pragmas:
-  /// #pragma GCC poison/system_header/dependency and #pragma once.
+  /// \#pragma GCC poison/system_header/dependency and \#pragma once.
   void RegisterBuiltinPragmas();
 
-  /// RegisterBuiltinMacros - Register builtin macros, such as __LINE__ with the
-  /// identifier table.
+  /// \brief Register builtin macros such as __LINE__ with the identifier table.
   void RegisterBuiltinMacros();
 
   /// HandleMacroExpandedIdentifier - If an identifier token is read that is to