<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">Thanks, and apologies for not re-compiling after my final edits.</div><div class="gmail_quote"><br></div><div class="gmail_quote">On Tue, Nov 26, 2013 at 5:44 PM, Chandler Carruth <span dir="ltr"><<a href="mailto:chandlerc@google.com" target="_blank">chandlerc@google.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr">Fixed in r195802.</div><div class="HOEnZb"><div class="h5"><div class="gmail_extra"><br><br><div class="gmail_quote">
On Tue, Nov 26, 2013 at 5:36 PM, Rafael Espíndola <span dir="ltr"><<a href="mailto:rafael.espindola@gmail.com" target="_blank">rafael.espindola@gmail.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">this broke the build<br>
<div><div><br>
On 26 November 2013 20:27, James Dennett <<a href="mailto:jdennett@google.com" target="_blank">jdennett@google.com</a>> wrote:<br>
> Author: jdennett<br>
> Date: Tue Nov 26 19:27:40 2013<br>
> New Revision: 195799<br>
><br>
> URL: <a href="http://llvm.org/viewvc/llvm-project?rev=195799&view=rev" target="_blank">http://llvm.org/viewvc/llvm-project?rev=195799&view=rev</a><br>
> Log:<br>
> Documentation cleanup: Doxygen-ification, typo fixes, and changing some of<br>
> the duplicated documentation from .cpp files so that it's not processed by<br>
> Doxygen and hence doesn't generate duplicate output.<br>
><br>
> Modified:<br>
> cfe/trunk/include/clang/Lex/Preprocessor.h<br>
> cfe/trunk/lib/Lex/PPCaching.cpp<br>
> cfe/trunk/lib/Lex/PPDirectives.cpp<br>
><br>
> Modified: cfe/trunk/include/clang/Lex/Preprocessor.h<br>
> URL: <a href="http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Lex/Preprocessor.h?rev=195799&r1=195798&r2=195799&view=diff" target="_blank">http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Lex/Preprocessor.h?rev=195799&r1=195798&r2=195799&view=diff</a><br>
> ==============================================================================<br>
> --- cfe/trunk/include/clang/Lex/Preprocessor.h (original)<br>
> +++ cfe/trunk/include/clang/Lex/Preprocessor.h Tue Nov 26 19:27:40 2013<br>
> @@ -6,9 +6,10 @@<br>
> // License. See LICENSE.TXT for details.<br>
> //<br>
> //===----------------------------------------------------------------------===//<br>
> -//<br>
> -// This file defines the Preprocessor interface.<br>
> -//<br>
> +///<br>
> +/// \file<br>
> +/// \brief Defines the clang::Preprocessor interface.<br>
> +///<br>
> //===----------------------------------------------------------------------===//<br>
><br>
> #ifndef LLVM_CLANG_LEX_PREPROCESSOR_H<br>
> @@ -78,11 +79,12 @@ public:<br>
> }<br>
> };<br>
><br>
> -/// Preprocessor - This object engages in a tight little dance with the lexer to<br>
> -/// efficiently preprocess tokens. Lexers know only about tokens within a<br>
> -/// single source file, and don't know anything about preprocessor-level issues<br>
> -/// like the \#include stack, token expansion, etc.<br>
> +/// \brief Engages in a tight little dance with the lexer to efficiently<br>
> +/// preprocess tokens.<br>
> ///<br>
> +/// Lexers know only about tokens within a single source file, and don't<br>
> +/// know anything about preprocessor-level issues like the \#include stack,<br>
> +/// token expansion, etc.<br>
> class Preprocessor : public RefCountedBase<Preprocessor> {<br>
> IntrusiveRefCntPtr<PreprocessorOptions> PPOpts;<br>
> DiagnosticsEngine *Diags;<br>
> @@ -98,12 +100,12 @@ class Preprocessor : public RefCountedBa<br>
> ExternalPreprocessorSource *ExternalSource;<br>
><br>
><br>
> - /// PTH - An optional PTHManager object used for getting tokens from<br>
> - /// a token cache rather than lexing the original source file.<br>
> + /// An optional PTHManager object used for getting tokens from<br>
> + /// a token cache rather than lexing the original source file.<br>
> OwningPtr<PTHManager> PTH;<br>
><br>
> - /// BP - A BumpPtrAllocator object used to quickly allocate and release<br>
> - /// objects internal to the Preprocessor.<br>
> + /// A BumpPtrAllocator object used to quickly allocate and release<br>
> + /// objects internal to the Preprocessor.<br>
> llvm::BumpPtrAllocator BP;<br>
><br>
> /// Identifiers for builtin macros and other builtins.<br>
> @@ -129,7 +131,7 @@ class Preprocessor : public RefCountedBa<br>
> unsigned CounterValue; // Next __COUNTER__ value.<br>
><br>
> enum {<br>
> - /// MaxIncludeStackDepth - Maximum depth of \#includes.<br>
> + /// \brief Maximum depth of \#includes.<br>
> MaxAllowedIncludeStackDepth = 200<br>
> };<br>
><br>
> @@ -144,12 +146,11 @@ class Preprocessor : public RefCountedBa<br>
> /// Whether the preprocessor owns the header search object.<br>
> bool OwnsHeaderSearch : 1;<br>
><br>
> - /// DisableMacroExpansion - True if macro expansion is disabled.<br>
> + /// True if macro expansion is disabled.<br>
> bool DisableMacroExpansion : 1;<br>
><br>
> - /// MacroExpansionInDirectivesOverride - Temporarily disables<br>
> - /// DisableMacroExpansion (i.e. enables expansion) when parsing preprocessor<br>
> - /// directives.<br>
> + /// Temporarily disables DisableMacroExpansion (i.e. enables expansion)<br>
> + /// when parsing preprocessor directives.<br>
> bool MacroExpansionInDirectivesOverride : 1;<br>
><br>
> class ResetMacroExpansionHelper;<br>
> @@ -169,23 +170,25 @@ class Preprocessor : public RefCountedBa<br>
> /// \brief True if we are pre-expanding macro arguments.<br>
> bool InMacroArgPreExpansion;<br>
><br>
> - /// Identifiers - This is mapping/lookup information for all identifiers in<br>
> + /// \brief Mapping/lookup information for all identifiers in<br>
> /// the program, including program keywords.<br>
> mutable IdentifierTable Identifiers;<br>
><br>
> - /// Selectors - This table contains all the selectors in the program. Unlike<br>
> - /// IdentifierTable above, this table *isn't* populated by the preprocessor.<br>
> - /// It is declared/expanded here because it's role/lifetime is<br>
> - /// conceptually similar the IdentifierTable. In addition, the current control<br>
> - /// flow (in clang::ParseAST()), make it convenient to put here.<br>
> + /// \brief This table contains all the selectors in the program.<br>
> + ///<br>
> + /// Unlike IdentifierTable above, this table *isn't* populated by the<br>
> + /// preprocessor. It is declared/expanded here because its role/lifetime is<br>
> + /// conceptually similar to the IdentifierTable. In addition, the current<br>
> + /// control flow (in clang::ParseAST()), make it convenient to put here.<br>
> + ///<br>
> /// FIXME: Make sure the lifetime of Identifiers/Selectors *isn't* tied to<br>
> /// the lifetime of the preprocessor.<br>
> SelectorTable Selectors;<br>
><br>
> - /// BuiltinInfo - Information about builtins.<br>
> + /// \brief Information about builtins.<br>
> Builtin::Context BuiltinInfo;<br>
><br>
> - /// PragmaHandlers - This tracks all of the pragmas that the client registered<br>
> + /// \brief Tracks all of the pragmas that the client registered<br>
> /// with this preprocessor.<br>
> PragmaNamespace *PragmaHandlers;<br>
><br>
> @@ -216,7 +219,7 @@ class Preprocessor : public RefCountedBa<br>
> /// for preprocessing.<br>
> SourceLocation CodeCompletionFileLoc;<br>
><br>
> - /// \brief The source location of the 'import' contextual keyword we just<br>
> + /// \brief The source location of the \c import contextual keyword we just<br>
> /// lexed, if any.<br>
> SourceLocation ModuleImportLoc;<br>
><br>
> @@ -226,45 +229,52 @@ class Preprocessor : public RefCountedBa<br>
> /// \brief Whether the last token we lexed was an '@'.<br>
> bool LastTokenWasAt;<br>
><br>
> - /// \brief Whether the module import expectes an identifier next. Otherwise,<br>
> + /// \brief Whether the module import expects an identifier next. Otherwise,<br>
> /// it expects a '.' or ';'.<br>
> bool ModuleImportExpectsIdentifier;<br>
><br>
> /// \brief The source location of the currently-active<br>
> - /// #pragma clang arc_cf_code_audited begin.<br>
> + /// \#pragma clang arc_cf_code_audited begin.<br>
> SourceLocation PragmaARCCFCodeAuditedLoc;<br>
><br>
> /// \brief True if we hit the code-completion point.<br>
> bool CodeCompletionReached;<br>
><br>
> /// \brief The number of bytes that we will initially skip when entering the<br>
> - /// main file, which is used when loading a precompiled preamble, along<br>
> - /// with a flag that indicates whether skipping this number of bytes will<br>
> - /// place the lexer at the start of a line.<br>
> + /// main file, along with a flag that indicates whether skipping this number<br>
> + /// of bytes will place the lexer at the start of a line.<br>
> + ///<br>
> + /// This is used when loading a precompiled preamble.<br>
> std::pair<unsigned, bool> SkipMainFilePreamble;<br>
><br>
> - /// CurLexer - This is the current top of the stack that we're lexing from if<br>
> + /// \brief The current top of the stack that we're lexing from if<br>
> /// not expanding a macro and we are lexing directly from source code.<br>
> - /// Only one of CurLexer, CurPTHLexer, or CurTokenLexer will be non-null.<br>
> + ///<br>
> + /// Only one of CurLexer, CurPTHLexer, or CurTokenLexer will be non-null.<br>
> OwningPtr<Lexer> CurLexer;<br>
><br>
> - /// CurPTHLexer - This is the current top of stack that we're lexing from if<br>
> - /// not expanding from a macro and we are lexing from a PTH cache.<br>
> - /// Only one of CurLexer, CurPTHLexer, or CurTokenLexer will be non-null.<br>
> + /// \brief The current top of stack that we're lexing from if<br>
> + /// not expanding from a macro and we are lexing from a PTH cache.<br>
> + ///<br>
> + /// Only one of CurLexer, CurPTHLexer, or CurTokenLexer will be non-null.<br>
> OwningPtr<PTHLexer> CurPTHLexer;<br>
><br>
> - /// CurPPLexer - This is the current top of the stack what we're lexing from<br>
> - /// if not expanding a macro. This is an alias for either CurLexer or<br>
> - /// CurPTHLexer.<br>
> + /// \brief The current top of the stack what we're lexing from<br>
> + /// if not expanding a macro.<br>
> + ///<br>
> + /// This is an alias for either CurLexer or CurPTHLexer.<br>
> PreprocessorLexer *CurPPLexer;<br>
><br>
> - /// CurLookup - The DirectoryLookup structure used to find the current<br>
> - /// FileEntry, if CurLexer is non-null and if applicable. This allows us to<br>
> - /// implement \#include_next and find directory-specific properties.<br>
> + /// \brief Used to find the current FileEntry, if CurLexer is non-null<br>
> + /// and if applicable.<br>
> + ///<br>
> + /// This allows us to implement \#include_next and find directory-specific<br>
> + /// properties.<br>
> const DirectoryLookup *CurDirLookup;<br>
><br>
> - /// CurTokenLexer - This is the current macro we are expanding, if we are<br>
> - /// expanding a macro. One of CurLexer and CurTokenLexer must be null.<br>
> + /// \brief The current macro we are expanding, if we are expanding a macro.<br>
> + ///<br>
> + /// One of CurLexer and CurTokenLexer must be null.<br>
> OwningPtr<TokenLexer> CurTokenLexer;<br>
><br>
> /// \brief The kind of lexer we're currently working with.<br>
> @@ -279,7 +289,7 @@ class Preprocessor : public RefCountedBa<br>
> /// \brief True if the current lexer is for a submodule.<br>
> bool CurIsSubmodule;<br>
><br>
> - /// IncludeMacroStack - This keeps track of the stack of files currently<br>
> + /// \brief Keeps track of the stack of files currently<br>
> /// \#included, and macros currently being expanded from, not counting<br>
> /// CurLexer/CurTokenLexer.<br>
> struct IncludeStackInfo {<br>
> @@ -299,7 +309,7 @@ class Preprocessor : public RefCountedBa<br>
> };<br>
> std::vector<IncludeStackInfo> IncludeMacroStack;<br>
><br>
> - /// Callbacks - These are actions invoked when some preprocessor activity is<br>
> + /// \brief Actions invoked when some preprocessor activity is<br>
> /// encountered (e.g. a file is \#included, etc).<br>
> PPCallbacks *Callbacks;<br>
><br>
> @@ -312,14 +322,16 @@ class Preprocessor : public RefCountedBa<br>
> };<br>
> SmallVector<MacroExpandsInfo, 2> DelayedMacroExpandsCallbacks;<br>
><br>
> - /// Macros - For each IdentifierInfo that was associated with a macro, we<br>
> + /// For each IdentifierInfo that was associated with a macro, we<br>
> /// keep a mapping to the history of all macro definitions and #undefs in<br>
> /// the reverse order (the latest one is in the head of the list).<br>
> llvm::DenseMap<const IdentifierInfo*, MacroDirective*> Macros;<br>
> friend class ASTReader;<br>
><br>
> /// \brief Macros that we want to warn because they are not used at the end<br>
> - /// of the translation unit; we store just their SourceLocations instead<br>
> + /// of the translation unit.<br>
> + ///<br>
> + /// We store just their SourceLocations instead of<br>
> /// something like MacroInfo*. The benefit of this is that when we are<br>
> /// deserializing from PCH, we don't need to deserialize identifier & macros<br>
> /// just so that we can report that they are unused, we just warn using<br>
> @@ -328,14 +340,13 @@ class Preprocessor : public RefCountedBa<br>
> typedef llvm::SmallPtrSet<SourceLocation, 32> WarnUnusedMacroLocsTy;<br>
> WarnUnusedMacroLocsTy WarnUnusedMacroLocs;<br>
><br>
> - /// MacroArgCache - This is a "freelist" of MacroArg objects that can be<br>
> + /// \brief A "freelist" of MacroArg objects that can be<br>
> /// reused for quick allocation.<br>
> MacroArgs *MacroArgCache;<br>
> friend class MacroArgs;<br>
><br>
> - /// PragmaPushMacroInfo - For each IdentifierInfo used in a #pragma<br>
> - /// push_macro directive, we keep a MacroInfo stack used to restore<br>
> - /// previous macro value.<br>
> + /// For each IdentifierInfo used in a \#pragma push_macro directive,<br>
> + /// we keep a MacroInfo stack used to restore the previous macro value.<br>
> llvm::DenseMap<IdentifierInfo*, std::vector<MacroInfo*> > PragmaPushMacroInfo;<br>
><br>
> // Various statistics we track for performance analysis.<br>
> @@ -346,17 +357,19 @@ class Preprocessor : public RefCountedBa<br>
> unsigned NumFastMacroExpanded, NumTokenPaste, NumFastTokenPaste;<br>
> unsigned NumSkipped;<br>
><br>
> - /// Predefines - This string is the predefined macros that preprocessor<br>
> - /// should use from the command line etc.<br>
> + /// \brief The predefined macros that preprocessor should use from the<br>
> + /// command line etc.<br>
> std::string Predefines;<br>
><br>
> /// \brief The file ID for the preprocessor predefines.<br>
> FileID PredefinesFileID;<br>
><br>
> - /// TokenLexerCache - Cache macro expanders to reduce malloc traffic.<br>
> + /// \{<br>
> + /// \brief Cache of macro expanders to reduce malloc traffic.<br>
> enum { TokenLexerCacheSize = 8 };<br>
> unsigned NumCachedTokenLexers;<br>
> TokenLexer *TokenLexerCache[TokenLexerCacheSize];<br>
> + /// \}<br>
><br>
> /// \brief Keeps macro expanded tokens for TokenLexers.<br>
> //<br>
> @@ -376,17 +389,20 @@ class Preprocessor : public RefCountedBa<br>
> private: // Cached tokens state.<br>
> typedef SmallVector<Token, 1> CachedTokensTy;<br>
><br>
> - /// CachedTokens - Cached tokens are stored here when we do backtracking or<br>
> + /// \brief Cached tokens are stored here when we do backtracking or<br>
> /// lookahead. They are "lexed" by the CachingLex() method.<br>
> CachedTokensTy CachedTokens;<br>
><br>
> - /// CachedLexPos - The position of the cached token that CachingLex() should<br>
> - /// "lex" next. If it points beyond the CachedTokens vector, it means that<br>
> - /// a normal Lex() should be invoked.<br>
> + /// \brief The position of the cached token that CachingLex() should<br>
> + /// "lex" next.<br>
> + ///<br>
> + /// If it points beyond the CachedTokens vector, it means that a normal<br>
> + /// Lex() should be invoked.<br>
> CachedTokensTy::size_type CachedLexPos;<br>
><br>
> - /// BacktrackPositions - Stack of backtrack positions, allowing nested<br>
> - /// backtracks. The EnableBacktrackAtThisPos() method pushes a position to<br>
> + /// \brief Stack of backtrack positions, allowing nested backtracks.<br>
> + ///<br>
> + /// The EnableBacktrackAtThisPos() method pushes a position to<br>
> /// indicate where CachedLexPos should be set when the BackTrack() method is<br>
> /// invoked (at which point the last position is popped).<br>
> std::vector<CachedTokensTy::size_type> BacktrackPositions;<br>
> @@ -401,7 +417,7 @@ private: // Cached tokens state.<br>
> /// of that list.<br>
> MacroInfoChain *MIChainHead;<br>
><br>
> - /// MICache - A "freelist" of MacroInfo objects that can be reused for quick<br>
> + /// A "freelist" of MacroInfo objects that can be reused for quick<br>
> /// allocation.<br>
> MacroInfoChain *MICache;<br>
><br>
> @@ -474,8 +490,7 @@ public:<br>
> return ParsingIfOrElifDirective;<br>
> }<br>
><br>
> - /// SetCommentRetentionState - Control whether or not the preprocessor retains<br>
> - /// comments in output.<br>
> + /// \brief Control whether the preprocessor retains comments in output.<br>
> void SetCommentRetentionState(bool KeepComments, bool KeepMacroComments) {<br>
> this->KeepComments = KeepComments | KeepMacroComments;<br>
> this->KeepMacroComments = KeepMacroComments;<br>
> @@ -504,26 +519,29 @@ public:<br>
> /// false if it is producing tokens to be consumed by Parse and Sema.<br>
> bool isPreprocessedOutput() const { return PreprocessedOutput; }<br>
><br>
> - /// isCurrentLexer - Return true if we are lexing directly from the specified<br>
> - /// lexer.<br>
> + /// \brief Return true if we are lexing directly from the specified lexer.<br>
> bool isCurrentLexer(const PreprocessorLexer *L) const {<br>
> return CurPPLexer == L;<br>
> }<br>
><br>
> - /// getCurrentLexer - Return the current lexer being lexed from. Note<br>
> - /// that this ignores any potentially active macro expansions and _Pragma<br>
> + /// \brief Return the current lexer being lexed from.<br>
> + ///<br>
> + /// Note that this ignores any potentially active macro expansions and _Pragma<br>
> /// expansions going on at the time.<br>
> PreprocessorLexer *getCurrentLexer() const { return CurPPLexer; }<br>
><br>
> - /// getCurrentFileLexer - Return the current file lexer being lexed from.<br>
> + /// \brief Return the current file lexer being lexed from.<br>
> + ///<br>
> /// Note that this ignores any potentially active macro expansions and _Pragma<br>
> /// expansions going on at the time.<br>
> PreprocessorLexer *getCurrentFileLexer() const;<br>
><br>
> - /// \brief Returns the file ID for the preprocessor predefines.<br>
> + /// \brief Returns the FileID for the preprocessor predefines.<br>
> FileID getPredefinesFileID() const { return PredefinesFileID; }<br>
><br>
> - /// getPPCallbacks/addPPCallbacks - Accessors for preprocessor callbacks.<br>
> + /// \{<br>
> + /// \brief Accessors for preprocessor callbacks.<br>
> + ///<br>
> /// Note that this class takes ownership of any PPCallbacks object given to<br>
> /// it.<br>
> PPCallbacks *getPPCallbacks() const { return Callbacks; }<br>
> @@ -532,9 +550,10 @@ public:<br>
> C = new PPChainedCallbacks(C, Callbacks);<br>
> Callbacks = C;<br>
> }<br>
> + /// \}<br>
><br>
> /// \brief Given an identifier, return its latest MacroDirective if it is<br>
> - // \#defined or null if it isn't \#define'd.<br>
> + /// \#defined or null if it isn't \#define'd.<br>
> MacroDirective *getMacroDirective(IdentifierInfo *II) const {<br>
> if (!II->hasMacroDefinition())<br>
> return 0;<br>
> @@ -555,9 +574,10 @@ public:<br>
> }<br>
><br>
> /// \brief Given an identifier, return the (probably #undef'd) MacroInfo<br>
> - /// representing the most recent macro definition. One can iterate over all<br>
> - /// previous macro definitions from it. This method should only be called for<br>
> - /// identifiers that hadMacroDefinition().<br>
> + /// representing the most recent macro definition.<br>
> + ///<br>
> + /// One can iterate over all previous macro definitions from the most recent<br>
> + /// one. This should only be called for identifiers that hadMacroDefinition().<br>
> MacroDirective *getMacroDirectiveHistory(const IdentifierInfo *II) const;<br>
><br>
> /// \brief Add a directive to the macro directive history for this identifier.<br>
> @@ -575,14 +595,15 @@ public:<br>
> /// \brief Set a MacroDirective that was loaded from a PCH file.<br>
> void setLoadedMacroDirective(IdentifierInfo *II, MacroDirective *MD);<br>
><br>
> - /// macro_iterator/macro_begin/macro_end - This allows you to walk the macro<br>
> - /// history table. Currently defined macros have<br>
> + /// \{<br>
> + /// Iterators for the macro history table. Currently defined macros have<br>
> /// IdentifierInfo::hasMacroDefinition() set and an empty<br>
> /// MacroInfo::getUndefLoc() at the head of the list.<br>
> typedef llvm::DenseMap<const IdentifierInfo *,<br>
> MacroDirective*>::const_iterator macro_iterator;<br>
> macro_iterator macro_begin(bool IncludeExternalMacros = true) const;<br>
> macro_iterator macro_end(bool IncludeExternalMacros = true) const;<br>
> + /// \}<br>
><br>
> /// \brief Return the name of the macro defined before \p Loc that has<br>
> /// spelling \p Tokens. If there are multiple macros with same spelling,<br>
> @@ -591,8 +612,9 @@ public:<br>
> ArrayRef<TokenValue> Tokens) const;<br>
><br>
> const std::string &getPredefines() const { return Predefines; }<br>
> - /// setPredefines - Set the predefines for this Preprocessor. These<br>
> - /// predefines are automatically injected when parsing the main file.<br>
> + /// \brief Set the predefines for this Preprocessor.<br>
> + ///<br>
> + /// These predefines are automatically injected when parsing the main file.<br>
> void setPredefines(const char *P) { Predefines = P; }<br>
> void setPredefines(const std::string &P) { Predefines = P; }<br>
><br>
> @@ -602,18 +624,20 @@ public:<br>
> return &Identifiers.get(Name);<br>
> }<br>
><br>
> - /// AddPragmaHandler - Add the specified pragma handler to the preprocessor.<br>
> - /// If 'Namespace' is non-null, then it is a token required to exist on the<br>
> + /// \brief Add the specified pragma handler to this preprocessor.<br>
> + ///<br>
> + /// If \p Namespace is non-null, then it is a token required to exist on the<br>
> /// pragma line before the pragma string starts, e.g. "STDC" or "GCC".<br>
> void AddPragmaHandler(StringRef Namespace, PragmaHandler *Handler);<br>
> void AddPragmaHandler(PragmaHandler *Handler) {<br>
> AddPragmaHandler(StringRef(), Handler);<br>
> }<br>
><br>
> - /// RemovePragmaHandler - Remove the specific pragma handler from<br>
> - /// the preprocessor. If \p Namespace is non-null, then it should<br>
> - /// be the namespace that \p Handler was added to. It is an error<br>
> - /// to remove a handler that has not been registered.<br>
> + /// \brief Remove the specific pragma handler from this preprocessor.<br>
> + ///<br>
> + /// If \p Namespace is non-null, then it should be the namespace that<br>
> + /// \p Handler was added to. It is an error to remove a handler that<br>
> + /// has not been registered.<br>
> void RemovePragmaHandler(StringRef Namespace, PragmaHandler *Handler);<br>
> void RemovePragmaHandler(PragmaHandler *Handler) {<br>
> RemovePragmaHandler(StringRef(), Handler);<br>
> @@ -654,51 +678,51 @@ public:<br>
> /// all macro expansions, macro definitions, etc.<br>
> void createPreprocessingRecord();<br>
><br>
> - /// EnterMainSourceFile - Enter the specified FileID as the main source file,<br>
> + /// \brief Enter the specified FileID as the main source file,<br>
> /// which implicitly adds the builtin defines etc.<br>
> void EnterMainSourceFile();<br>
><br>
> - /// EndSourceFile - Inform the preprocessor callbacks that processing is<br>
> - /// complete.<br>
> + /// \brief Inform the preprocessor callbacks that processing is complete.<br>
> void EndSourceFile();<br>
><br>
> - /// EnterSourceFile - Add a source file to the top of the include stack and<br>
> - /// start lexing tokens from it instead of the current buffer. Emit an error<br>
> - /// and don't enter the file on error.<br>
> + /// \brief Add a source file to the top of the include stack and<br>
> + /// start lexing tokens from it instead of the current buffer.<br>
> + ///<br>
> + /// Emit an error and don't enter the file on error.<br>
> void EnterSourceFile(FileID CurFileID, const DirectoryLookup *Dir,<br>
> SourceLocation Loc, bool IsSubmodule = false);<br>
><br>
> - /// EnterMacro - Add a Macro to the top of the include stack and start lexing<br>
> - /// tokens from it instead of the current buffer. Args specifies the<br>
> - /// tokens input to a function-like macro.<br>
> + /// \brief Add a Macro to the top of the include stack and start lexing<br>
> + /// tokens from it instead of the current buffer.<br>
> ///<br>
> - /// ILEnd specifies the location of the ')' for a function-like macro or the<br>
> - /// identifier for an object-like macro.<br>
> + /// \param Args specifies the tokens input to a function-like macro.<br>
> + /// \param ILEnd specifies the location of the ')' for a function-like macro<br>
> + /// or the identifier for an object-like macro.<br>
> void EnterMacro(Token &Identifier, SourceLocation ILEnd, MacroInfo *Macro,<br>
> MacroArgs *Args);<br>
><br>
> - /// EnterTokenStream - Add a "macro" context to the top of the include stack,<br>
> + /// \brief Add a "macro" context to the top of the include stack,<br>
> /// which will cause the lexer to start returning the specified tokens.<br>
> ///<br>
> - /// If DisableMacroExpansion is true, tokens lexed from the token stream will<br>
> - /// not be subject to further macro expansion. Otherwise, these tokens will<br>
> - /// be re-macro-expanded when/if expansion is enabled.<br>
> - ///<br>
> - /// If OwnsTokens is false, this method assumes that the specified stream of<br>
> - /// tokens has a permanent owner somewhere, so they do not need to be copied.<br>
> - /// If it is true, it assumes the array of tokens is allocated with new[] and<br>
> - /// must be freed.<br>
> - ///<br>
> + /// If \p DisableMacroExpansion is true, tokens lexed from the token stream<br>
> + /// will not be subject to further macro expansion. Otherwise, these tokens<br>
> + /// will be re-macro-expanded when/if expansion is enabled.<br>
> + ///<br>
> + /// If \p OwnsTokens is false, this method assumes that the specified stream<br>
> + /// of tokens has a permanent owner somewhere, so they do not need to be<br>
> + /// copied. If it is true, it assumes the array of tokens is allocated with<br>
> + /// \c new[] and must be freed.<br>
> void EnterTokenStream(const Token *Toks, unsigned NumToks,<br>
> bool DisableMacroExpansion, bool OwnsTokens);<br>
><br>
> - /// RemoveTopOfLexerStack - Pop the current lexer/macro exp off the top of the<br>
> - /// lexer stack. This should only be used in situations where the current<br>
> - /// state of the top-of-stack lexer is known.<br>
> + /// \brief Pop the current lexer/macro exp off the top of the lexer stack.<br>
> + ///<br>
> + /// This should only be used in situations where the current state of the<br>
> + /// top-of-stack lexer is known.<br>
> void RemoveTopOfLexerStack();<br>
><br>
> - /// EnableBacktrackAtThisPos - From the point that this method is called, and<br>
> - /// until CommitBacktrackedTokens() or Backtrack() is called, the Preprocessor<br>
> + /// From the point that this method is called, and until<br>
> + /// CommitBacktrackedTokens() or Backtrack() is called, the Preprocessor<br>
> /// keeps track of the lexed tokens so that a subsequent Backtrack() call will<br>
> /// make the Preprocessor re-lex the same tokens.<br>
> ///<br>
> @@ -712,18 +736,18 @@ public:<br>
> ///<br>
> void EnableBacktrackAtThisPos();<br>
><br>
> - /// CommitBacktrackedTokens - Disable the last EnableBacktrackAtThisPos call.<br>
> + /// \brief Disable the last EnableBacktrackAtThisPos call.<br>
> void CommitBacktrackedTokens();<br>
><br>
> - /// Backtrack - Make Preprocessor re-lex the tokens that were lexed since<br>
> + /// \brief Make Preprocessor re-lex the tokens that were lexed since<br>
> /// EnableBacktrackAtThisPos() was previously called.<br>
> void Backtrack();<br>
><br>
> - /// isBacktrackEnabled - True if EnableBacktrackAtThisPos() was called and<br>
> + /// \brief True if EnableBacktrackAtThisPos() was called and<br>
> /// caching of tokens is on.<br>
> bool isBacktrackEnabled() const { return !BacktrackPositions.empty(); }<br>
><br>
> - /// Lex - Lex the next token for this preprocessor.<br>
> + /// \brief Lex the next token for this preprocessor.<br>
> void Lex(Token &Result);<br>
><br>
> void LexAfterModuleImport(Token &Result);<br>
> @@ -747,17 +771,18 @@ public:<br>
> const char *DiagnosticTag,<br>
> bool AllowMacroExpansion);<br>
><br>
> - /// LexNonComment - Lex a token. If it's a comment, keep lexing until we get<br>
> - /// something not a comment. This is useful in -E -C mode where comments<br>
> - /// would foul up preprocessor directive handling.<br>
> + /// \brief Lex a token. If it's a comment, keep lexing until we get<br>
> + /// something not a comment.<br>
> + ///<br>
> + /// This is useful in -E -C mode where comments would foul up preprocessor<br>
> + /// directive handling.<br>
> void LexNonComment(Token &Result) {<br>
> do<br>
> Lex(Result);<br>
> while (Result.getKind() == tok::comment);<br>
> }<br>
><br>
> - /// LexUnexpandedToken - This is just like Lex, but this disables macro<br>
> - /// expansion of identifier tokens.<br>
> + /// \brief Just like Lex, but disables macro expansion of identifier tokens.<br>
> void LexUnexpandedToken(Token &Result) {<br>
> // Disable macro expansion.<br>
> bool OldVal = DisableMacroExpansion;<br>
> @@ -769,8 +794,8 @@ public:<br>
> DisableMacroExpansion = OldVal;<br>
> }<br>
><br>
> - /// LexUnexpandedNonComment - Like LexNonComment, but this disables macro<br>
> - /// expansion of identifier tokens.<br>
> + /// \brief Like LexNonComment, but this disables macro expansion of<br>
> + /// identifier tokens.<br>
> void LexUnexpandedNonComment(Token &Result) {<br>
> do<br>
> LexUnexpandedToken(Result);<br>
> @@ -783,10 +808,12 @@ public:<br>
> MacroExpansionInDirectivesOverride = true;<br>
> }<br>
><br>
> - /// LookAhead - This peeks ahead N tokens and returns that token without<br>
> - /// consuming any tokens. LookAhead(0) returns the next token that would be<br>
> - /// returned by Lex(), LookAhead(1) returns the token after it, etc. This<br>
> - /// returns normal tokens after phase 5. As such, it is equivalent to using<br>
> + /// \brief Peeks ahead N tokens and returns that token without consuming any<br>
> + /// tokens.<br>
> + ///<br>
> + /// LookAhead(0) returns the next token that would be returned by Lex(),<br>
> + /// LookAhead(1) returns the token after it, etc. This returns normal<br>
> + /// tokens after phase 5. As such, it is equivalent to using<br>
> /// 'Lex', not 'LexUnexpandedToken'.<br>
> const Token &LookAhead(unsigned N) {<br>
> if (CachedLexPos + N < CachedTokens.size())<br>
> @@ -795,8 +822,9 @@ public:<br>
> return PeekAhead(N+1);<br>
> }<br>
><br>
> - /// RevertCachedTokens - When backtracking is enabled and tokens are cached,<br>
> + /// \brief When backtracking is enabled and tokens are cached,<br>
> /// this allows to revert a specific number of tokens.<br>
> + ///<br>
> /// Note that the number of tokens being reverted should be up to the last<br>
> /// backtrack position, not more.<br>
> void RevertCachedTokens(unsigned N) {<br>
> @@ -809,20 +837,21 @@ public:<br>
> CachedLexPos -= N;<br>
> }<br>
><br>
> - /// EnterToken - Enters a token in the token stream to be lexed next. If<br>
> - /// BackTrack() is called afterwards, the token will remain at the insertion<br>
> - /// point.<br>
> + /// \brief Enters a token in the token stream to be lexed next.<br>
> + ///<br>
> + /// If BackTrack() is called afterwards, the token will remain at the<br>
> + /// insertion point.<br>
> void EnterToken(const Token &Tok) {<br>
> EnterCachingLexMode();<br>
> CachedTokens.insert(CachedTokens.begin()+CachedLexPos, Tok);<br>
> }<br>
><br>
> - /// AnnotateCachedTokens - We notify the Preprocessor that if it is caching<br>
> - /// tokens (because backtrack is enabled) it should replace the most recent<br>
> - /// cached tokens with the given annotation token. This function has no effect<br>
> - /// if backtracking is not enabled.<br>
> + /// We notify the Preprocessor that if it is caching tokens (because<br>
> + /// backtrack is enabled) it should replace the most recent cached tokens<br>
> + /// with the given annotation token. This function has no effect if<br>
> + /// backtracking is not enabled.<br>
> ///<br>
> - /// Note that the use of this function is just for optimization; so that the<br>
> + /// Note that the use of this function is just for optimization, so that the<br>
> /// cached tokens doesn't get re-parsed and re-resolved after a backtrack is<br>
> /// invoked.<br>
> void AnnotateCachedTokens(const Token &Tok) {<br>
> @@ -852,7 +881,7 @@ public:<br>
> CachedTokens[CachedLexPos-1] = Tok;<br>
> }<br>
><br>
> - /// TypoCorrectToken - Update the current token to represent the provided<br>
> + /// Update the current token to represent the provided<br>
> /// identifier, in order to cache an action performed by typo correction.<br>
> void TypoCorrectToken(const Token &Tok) {<br>
> assert(Tok.getIdentifierInfo() && "Expected identifier token");<br>
> @@ -893,11 +922,13 @@ public:<br>
> bool isCodeCompletionEnabled() const { return CodeCompletionFile != 0; }<br>
><br>
> /// \brief Returns the location of the code-completion point.<br>
> + ///<br>
> /// Returns an invalid location if code-completion is not enabled or the file<br>
> /// containing the code-completion point has not been lexed yet.<br>
> SourceLocation getCodeCompletionLoc() const { return CodeCompletionLoc; }<br>
><br>
> /// \brief Returns the start location of the file of code-completion point.<br>
> + ///<br>
> /// Returns an invalid location if code-completion is not enabled or the file<br>
> /// containing the code-completion point has not been lexed yet.<br>
> SourceLocation getCodeCompletionFileLoc() const {<br>
> @@ -917,8 +948,9 @@ public:<br>
> }<br>
><br>
> /// \brief The location of the currently-active \#pragma clang<br>
> - /// arc_cf_code_audited begin. Returns an invalid location if there<br>
> - /// is no such pragma active.<br>
> + /// arc_cf_code_audited begin.<br>
> + ///<br>
> + /// Returns an invalid location if there is no such pragma active.<br>
> SourceLocation getPragmaARCCFCodeAuditedLoc() const {<br>
> return PragmaARCCFCodeAuditedLoc;<br>
> }<br>
> @@ -940,7 +972,7 @@ public:<br>
> SkipMainFilePreamble.second = StartOfLine;<br>
> }<br>
><br>
> - /// Diag - Forwarding function for diagnostics. This emits a diagnostic at<br>
> + /// Forwarding function for diagnostics. This emits a diagnostic at<br>
> /// the specified Token's location, translating the token's start<br>
> /// position in the current buffer into a SourcePosition object for rendering.<br>
> DiagnosticBuilder Diag(SourceLocation Loc, unsigned DiagID) const {<br>
> @@ -951,7 +983,7 @@ public:<br>
> return Diags->Report(Tok.getLocation(), DiagID);<br>
> }<br>
><br>
> - /// getSpelling() - Return the 'spelling' of the token at the given<br>
> + /// Return the 'spelling' of the token at the given<br>
> /// location; does not go up to the spelling location or down to the<br>
> /// expansion location.<br>
> ///<br>
> @@ -964,21 +996,24 @@ public:<br>
> return Lexer::getSpelling(loc, buffer, SourceMgr, LangOpts, invalid);<br>
> }<br>
><br>
> - /// getSpelling() - Return the 'spelling' of the Tok token. The spelling of a<br>
> - /// token is the characters used to represent the token in the source file<br>
> - /// after trigraph expansion and escaped-newline folding. In particular, this<br>
> - /// wants to get the true, uncanonicalized, spelling of things like digraphs<br>
> - /// UCNs, etc.<br>
> + /// \brief Return the 'spelling' of the Tok token.<br>
> + ///<br>
> + /// The spelling of a token is the characters used to represent the token in<br>
> + /// the source file after trigraph expansion and escaped-newline folding. In<br>
> + /// particular, this wants to get the true, uncanonicalized, spelling of<br>
> + /// things like digraphs, UCNs, etc.<br>
> ///<br>
> /// \param Invalid If non-null, will be set \c true if an error occurs.<br>
> std::string getSpelling(const Token &Tok, bool *Invalid = 0) const {<br>
> return Lexer::getSpelling(Tok, SourceMgr, LangOpts, Invalid);<br>
> }<br>
><br>
> - /// getSpelling - This method is used to get the spelling of a token into a<br>
> - /// preallocated buffer, instead of as an std::string. The caller is required<br>
> - /// to allocate enough space for the token, which is guaranteed to be at least<br>
> - /// Tok.getLength() bytes long. The length of the actual result is returned.<br>
> + /// \brief Get the spelling of a token into a preallocated buffer, instead<br>
> + /// of as an std::string.<br>
> + ///<br>
> + /// The caller is required to allocate enough space for the token, which is<br>
> + /// guaranteed to be at least Tok.getLength() bytes long. The length of the<br>
> + /// actual result is returned.<br>
> ///<br>
> /// Note that this method may do two possible things: it may either fill in<br>
> /// the buffer specified with characters, or it may *change the input pointer*<br>
> @@ -990,8 +1025,9 @@ public:<br>
> return Lexer::getSpelling(Tok, Buffer, SourceMgr, LangOpts, Invalid);<br>
> }<br>
><br>
> - /// getSpelling - This method is used to get the spelling of a token into a<br>
> - /// SmallVector. Note that the returned StringRef may not point to the<br>
> + /// \brief Get the spelling of a token into a SmallVector.<br>
> + ///<br>
> + /// Note that the returned StringRef may not point to the<br>
> /// supplied buffer if a copy can be avoided.<br>
> StringRef getSpelling(const Token &Tok,<br>
> SmallVectorImpl<char> &Buffer,<br>
> @@ -1004,8 +1040,8 @@ public:<br>
> return Lexer::getRawToken(Loc, Result, SourceMgr, LangOpts, IgnoreWhiteSpace);<br>
> }<br>
><br>
> - /// getSpellingOfSingleCharacterNumericConstant - Tok is a numeric constant<br>
> - /// with length 1, return the character.<br>
> + /// \brief Given a Token \p Tok that is a numeric constant with length 1,<br>
> + /// return the character.<br>
> char getSpellingOfSingleCharacterNumericConstant(const Token &Tok,<br>
> bool *Invalid = 0) const {<br>
> assert(Tok.is(tok::numeric_constant) &&<br>
> @@ -1023,18 +1059,21 @@ public:<br>
><br>
> /// \brief Retrieve the name of the immediate macro expansion.<br>
> ///<br>
> - /// This routine starts from a source location, and finds the name of the macro<br>
> - /// responsible for its immediate expansion. It looks through any intervening<br>
> - /// macro argument expansions to compute this. It returns a StringRef which<br>
> - /// refers to the SourceManager-owned buffer of the source where that macro<br>
> - /// name is spelled. Thus, the result shouldn't out-live the SourceManager.<br>
> + /// This routine starts from a source location, and finds the name of the<br>
> + /// macro responsible for its immediate expansion. It looks through any<br>
> + /// intervening macro argument expansions to compute this. It returns a<br>
> + /// StringRef that refers to the SourceManager-owned buffer of the source<br>
> + /// where that macro name is spelled. Thus, the result shouldn't out-live<br>
> + /// the SourceManager.<br>
> StringRef getImmediateMacroName(SourceLocation Loc) {<br>
> return Lexer::getImmediateMacroName(Loc, SourceMgr, getLangOpts());<br>
> }<br>
><br>
> - /// CreateString - Plop the specified string into a scratch buffer and set the<br>
> - /// specified token's location and length to it. If specified, the source<br>
> - /// location provides a location of the expansion point of the token.<br>
> + /// \brief Plop the specified string into a scratch buffer and set the<br>
> + /// specified token's location and length to it.<br>
> + ///<br>
> + /// If specified, the source location provides a location of the expansion<br>
> + /// point of the token.<br>
> void CreateString(StringRef Str, Token &Tok,<br>
> SourceLocation ExpansionLocStart = SourceLocation(),<br>
> SourceLocation ExpansionLocEnd = SourceLocation());<br>
> @@ -1079,23 +1118,22 @@ public:<br>
> return Lexer::isAtEndOfMacroExpansion(loc, SourceMgr, LangOpts, MacroEnd);<br>
> }<br>
><br>
> - /// DumpToken - Print the token to stderr, used for debugging.<br>
> - ///<br>
> + /// \brief Print the token to stderr, used for debugging.<br>
> void DumpToken(const Token &Tok, bool DumpFlags = false) const;<br>
> void DumpLocation(SourceLocation Loc) const;<br>
> void DumpMacro(const MacroInfo &MI) const;<br>
><br>
> - /// AdvanceToTokenCharacter - Given a location that specifies the start of a<br>
> + /// \brief Given a location that specifies the start of a<br>
> /// token, return a new location that specifies a character within the token.<br>
> SourceLocation AdvanceToTokenCharacter(SourceLocation TokStart,<br>
> unsigned Char) const {<br>
> return Lexer::AdvanceToTokenCharacter(TokStart, Char, SourceMgr, LangOpts);<br>
> }<br>
><br>
> - /// IncrementPasteCounter - Increment the counters for the number of token<br>
> - /// paste operations performed. If fast was specified, this is a 'fast paste'<br>
> - /// case we handled.<br>
> + /// \brief Increment the counters for the number of token paste operations<br>
> + /// performed.<br>
> ///<br>
> + /// If fast was specified, this is a 'fast paste' case we handled.<br>
> void IncrementPasteCounter(bool isFast) {<br>
> if (isFast)<br>
> ++NumFastTokenPaste;<br>
> @@ -1107,16 +1145,16 @@ public:<br>
><br>
> size_t getTotalMemory() const;<br>
><br>
> - /// HandleMicrosoftCommentPaste - When the macro expander pastes together a<br>
> - /// comment (/##/) in microsoft mode, this method handles updating the current<br>
> - /// state, returning the token on the next source line.<br>
> + /// When the macro expander pastes together a comment (/##/) in Microsoft<br>
> + /// mode, this method handles updating the current state, returning the<br>
> + /// token on the next source line.<br>
> void HandleMicrosoftCommentPaste(Token &Tok);<br>
><br>
> //===--------------------------------------------------------------------===//<br>
> // Preprocessor callback methods. These are invoked by a lexer as various<br>
> // directives and events are found.<br>
><br>
> - /// LookUpIdentifierInfo - Given a tok::raw_identifier token, look up the<br>
> + /// Given a tok::raw_identifier token, look up the<br>
> /// identifier information for the token and install it into the token,<br>
> /// updating the token kind accordingly.<br>
> IdentifierInfo *LookUpIdentifierInfo(Token &Identifier) const;<br>
> @@ -1126,14 +1164,13 @@ private:<br>
><br>
> public:<br>
><br>
> - // SetPoisonReason - Call this function to indicate the reason for<br>
> - // poisoning an identifier. If that identifier is accessed while<br>
> - // poisoned, then this reason will be used instead of the default<br>
> - // "poisoned" diagnostic.<br>
> + /// \brief Specifies the reason for poisoning an identifier.<br>
> + ///<br>
> + /// If that identifier is accessed while poisoned, then this reason will be<br>
> + /// used instead of the default "poisoned" diagnostic.<br>
> void SetPoisonReason(IdentifierInfo *II, unsigned DiagID);<br>
><br>
> - // HandlePoisonedIdentifier - Display reason for poisoned<br>
> - // identifier.<br>
> + /// \brief Display reason for poisoned identifier.<br>
> void HandlePoisonedIdentifier(Token & Tok);<br>
><br>
> void MaybeHandlePoisonedIdentifier(Token & Identifier) {<br>
> @@ -1165,42 +1202,47 @@ private:<br>
> public:<br>
> void PoisonSEHIdentifiers(bool Poison = true); // Borland<br>
><br>
> - /// HandleIdentifier - This callback is invoked when the lexer reads an<br>
> - /// identifier and has filled in the tokens IdentifierInfo member. This<br>
> - /// callback potentially macro expands it or turns it into a named token (like<br>
> - /// 'for').<br>
> + /// \brief Callback invoked when the lexer reads an identifier and has<br>
> + /// filled in the tokens IdentifierInfo member.<br>
> + ///<br>
> + /// This callback potentially macro expands it or turns it into a named<br>
> + /// token (like 'for').<br>
> ///<br>
> /// \returns true if we actually computed a token, false if we need to<br>
> /// lex again.<br>
> bool HandleIdentifier(Token &Identifier);<br>
><br>
><br>
> - /// HandleEndOfFile - This callback is invoked when the lexer hits the end of<br>
> - /// the current file. This either returns the EOF token and returns true, or<br>
> + /// \brief Callback invoked when the lexer hits the end of the current file.<br>
> + ///<br>
> + /// This either returns the EOF token and returns true, or<br>
> /// pops a level off the include stack and returns false, at which point the<br>
> /// client should call lex again.<br>
> bool HandleEndOfFile(Token &Result, bool isEndOfMacro = false);<br>
><br>
> - /// HandleEndOfTokenLexer - This callback is invoked when the current<br>
> - /// TokenLexer hits the end of its token stream.<br>
> + /// \brief Callback invoked when the current TokenLexer hits the end of its<br>
> + /// token stream.<br>
> bool HandleEndOfTokenLexer(Token &Result);<br>
><br>
> - /// HandleDirective - This callback is invoked when the lexer sees a # token<br>
> - /// at the start of a line. This consumes the directive, modifies the<br>
> - /// lexer/preprocessor state, and advances the lexer(s) so that the next token<br>
> - /// read is the correct one.<br>
> + /// \brief Callback invoked when the lexer sees a # token at the start of a<br>
> + /// line.<br>
> + ///<br>
> + /// This consumes the directive, modifies the lexer/preprocessor state, and<br>
> + /// advances the lexer(s) so that the next token read is the correct one.<br>
> void HandleDirective(Token &Result);<br>
><br>
> - /// CheckEndOfDirective - Ensure that the next token is a tok::eod token. If<br>
> - /// not, emit a diagnostic and consume up until the eod. If EnableMacros is<br>
> - /// true, then we consider macros that expand to zero tokens as being ok.<br>
> + /// \brief Ensure that the next token is a tok::eod token.<br>
> + ///<br>
> + /// If not, emit a diagnostic and consume up until the eod.<br>
> + /// If \p EnableMacros is true, then we consider macros that expand to zero<br>
> + /// tokens as being ok.<br>
> void CheckEndOfDirective(const char *Directive, bool EnableMacros = false);<br>
><br>
> - /// DiscardUntilEndOfDirective - Read and discard all tokens remaining on the<br>
> - /// current line until the tok::eod token is found.<br>
> + /// \brief Read and discard all tokens remaining on the current line until<br>
> + /// the tok::eod token is found.<br>
> void DiscardUntilEndOfDirective();<br>
><br>
> - /// SawDateOrTime - This returns true if the preprocessor has seen a use of<br>
> + /// \brief Returns true if the preprocessor has seen a use of<br>
> /// __DATE__ or __TIME__ in the file so far.<br>
> bool SawDateOrTime() const {<br>
> return DATELoc != SourceLocation() || TIMELoc != SourceLocation();<br>
> @@ -1241,17 +1283,20 @@ public:<br>
> ModuleMap::KnownHeader *SuggestedModule,<br>
> bool SkipCache = false);<br>
><br>
> - /// GetCurLookup - The DirectoryLookup structure used to find the current<br>
> - /// FileEntry, if CurLexer is non-null and if applicable. This allows us to<br>
> - /// implement \#include_next and find directory-specific properties.<br>
> + /// \brief Get the DirectoryLookup structure used to find the current<br>
> + /// FileEntry, if CurLexer is non-null and if applicable.<br>
> + ///<br>
> + /// This allows us to implement \#include_next and find directory-specific<br>
> + /// properties.<br>
> const DirectoryLookup *GetCurDirLookup() { return CurDirLookup; }<br>
><br>
> /// \brief Return true if we're in the top-level file, not in a \#include.<br>
> bool isInPrimaryFile() const;<br>
><br>
> - /// ConcatenateIncludeName - Handle cases where the \#include name is expanded<br>
> - /// from a macro as multiple tokens, which need to be glued together. This<br>
> - /// occurs for code like:<br>
> + /// \brief Handle cases where the \#include name is expanded<br>
> + /// from a macro as multiple tokens, which need to be glued together.<br>
> + ///<br>
> + /// This occurs for code like:<br>
> /// \code<br>
> /// \#define FOO <x/y.h><br>
> /// \#include FOO<br>
> @@ -1264,7 +1309,7 @@ public:<br>
> bool ConcatenateIncludeName(SmallString<128> &FilenameBuffer,<br>
> SourceLocation &End);<br>
><br>
> - /// LexOnOffSwitch - Lex an on-off-switch (C99 6.10.6p2) and verify that it is<br>
> + /// \brief Lex an on-off-switch (C99 6.10.6p2) and verify that it is<br>
> /// followed by EOD. Return true if the token is not a valid on-off-switch.<br>
> bool LexOnOffSwitch(tok::OnOffSwitch &OOS);<br>
><br>
> @@ -1309,15 +1354,16 @@ private:<br>
> /// This memory will be reused for allocating new MacroInfo objects.<br>
> void ReleaseMacroInfo(MacroInfo* MI);<br>
><br>
> - /// ReadMacroName - Lex and validate a macro name, which occurs after a<br>
> - /// \#define or \#undef. This emits a diagnostic, sets the token kind to eod,<br>
> + /// \brief Lex and validate a macro name, which occurs after a<br>
> + /// \#define or \#undef.<br>
> + ///<br>
> + /// This emits a diagnostic, sets the token kind to eod,<br>
> /// and discards the rest of the macro line if the macro name is invalid.<br>
> void ReadMacroName(Token &MacroNameTok, char isDefineUndef = 0);<br>
><br>
> - /// ReadMacroDefinitionArgList - The ( starting an argument list of a macro<br>
> - /// definition has just been read. Lex the rest of the arguments and the<br>
> - /// closing ), updating MI with what we learn and saving in LastTok the<br>
> - /// last token read.<br>
> + /// The ( starting an argument list of a macro definition has just been read.<br>
> + /// Lex the rest of the arguments and the closing ), updating \p MI with<br>
> + /// what we learn and saving in \p LastTok the last token read.<br>
> /// Return true if an error occurs parsing the arg list.<br>
> bool ReadMacroDefinitionArgList(MacroInfo *MI, Token& LastTok);<br>
><br>
> @@ -1336,21 +1382,22 @@ private:<br>
> /// \brief A fast PTH version of SkipExcludedConditionalBlock.<br>
> void PTHSkipExcludedConditionalBlock();<br>
><br>
> - /// EvaluateDirectiveExpression - Evaluate an integer constant expression that<br>
> - /// may occur after a #if or #elif directive and return it as a bool. If the<br>
> - /// expression is equivalent to "!defined(X)" return X in IfNDefMacro.<br>
> + /// \brief Evaluate an integer constant expression that may occur after a<br>
> + /// \#if or \#elif directive and return it as a bool.<br>
> + ///<br>
> + /// If the expression is equivalent to "!defined(X)" return X in IfNDefMacro.<br>
> bool EvaluateDirectiveExpression(IdentifierInfo *&IfNDefMacro);<br>
><br>
> - /// RegisterBuiltinPragmas - Install the standard preprocessor pragmas:<br>
> + /// \brief Install the standard preprocessor pragmas:<br>
> /// \#pragma GCC poison/system_header/dependency and \#pragma once.<br>
> void RegisterBuiltinPragmas();<br>
><br>
> /// \brief Register builtin macros such as __LINE__ with the identifier table.<br>
> void RegisterBuiltinMacros();<br>
><br>
> - /// HandleMacroExpandedIdentifier - If an identifier token is read that is to<br>
> - /// be expanded as a macro, handle it and return the next token as 'Tok'. If<br>
> - /// we lexed a token, return true; otherwise the caller should lex again.<br>
> + /// If an identifier token is read that is to be expanded as a macro, handle<br>
> + /// it and return the next token as 'Tok'. If we lexed a token, return true;<br>
> + /// otherwise the caller should lex again.<br>
> bool HandleMacroExpandedIdentifier(Token &Tok, MacroDirective *MD);<br>
><br>
> /// \brief Cache macro expanded tokens for TokenLexers.<br>
> @@ -1363,48 +1410,47 @@ private:<br>
> void removeCachedMacroExpandedTokensOfLastLexer();<br>
> friend void TokenLexer::ExpandFunctionArguments();<br>
><br>
> - /// isNextPPTokenLParen - Determine whether the next preprocessor token to be<br>
> + /// Determine whether the next preprocessor token to be<br>
> /// lexed is a '('. If so, consume the token and return true, if not, this<br>
> /// method should have no observable side-effect on the lexed tokens.<br>
> bool isNextPPTokenLParen();<br>
><br>
> - /// ReadFunctionLikeMacroArgs - After reading "MACRO(", this method is<br>
> - /// invoked to read all of the formal arguments specified for the macro<br>
> - /// invocation. This returns null on error.<br>
> + /// After reading "MACRO(", this method is invoked to read all of the formal<br>
> + /// arguments specified for the macro invocation. Returns null on error.<br>
> MacroArgs *ReadFunctionLikeMacroArgs(Token &MacroName, MacroInfo *MI,<br>
> SourceLocation &ExpansionEnd);<br>
><br>
> - /// ExpandBuiltinMacro - If an identifier token is read that is to be expanded<br>
> + /// \brief If an identifier token is read that is to be expanded<br>
> /// as a builtin macro, handle it and return the next token as 'Tok'.<br>
> void ExpandBuiltinMacro(Token &Tok);<br>
><br>
> - /// Handle_Pragma - Read a _Pragma directive, slice it up, process it, then<br>
> - /// return the first token after the directive. The _Pragma token has just<br>
> - /// been read into 'Tok'.<br>
> + /// \brief Read a \c _Pragma directive, slice it up, process it, then<br>
> + /// return the first token after the directive.<br>
> + /// This assumes that the \c _Pragma token has just been read into \p Tok.<br>
> void Handle_Pragma(Token &Tok);<br>
><br>
> - /// HandleMicrosoft__pragma - Like Handle_Pragma except the pragma text<br>
> - /// is not enclosed within a string literal.<br>
> + /// \brief Like Handle_Pragma except the pragma text is not enclosed within<br>
> + /// a string literal.<br>
> void HandleMicrosoft__pragma(Token &Tok);<br>
><br>
> - /// EnterSourceFileWithLexer - Add a lexer to the top of the include stack and<br>
> + /// \brief Add a lexer to the top of the include stack and<br>
> /// start lexing tokens from it instead of the current buffer.<br>
> void EnterSourceFileWithLexer(Lexer *TheLexer, const DirectoryLookup *Dir,<br>
> bool IsSubmodule = false);<br>
><br>
> - /// EnterSourceFileWithPTH - Add a lexer to the top of the include stack and<br>
> + /// \brief Add a lexer to the top of the include stack and<br>
> /// start getting tokens from it using the PTH cache.<br>
> void EnterSourceFileWithPTH(PTHLexer *PL, const DirectoryLookup *Dir,<br>
> bool IsSubmodule = false);<br>
><br>
> - /// \brief Set the file ID for the preprocessor predefines.<br>
> + /// \brief Set the FileID for the preprocessor predefines.<br>
> void setPredefinesFileID(FileID FID) {<br>
> assert(PredefinesFileID.isInvalid() && "PredefinesFileID already set!");<br>
> PredefinesFileID = FID;<br>
> }<br>
><br>
> - /// IsFileLexer - Returns true if we are lexing from a file and not a<br>
> - /// pragma or a macro.<br>
> + /// \brief Returns true if we are lexing from a file and not a<br>
> + /// pragma or a macro.<br>
> static bool IsFileLexer(const Lexer* L, const PreprocessorLexer* P) {<br>
> return L ? !L->isPragmaLexer() : P != 0;<br>
> }<br>
><br>
> Modified: cfe/trunk/lib/Lex/PPCaching.cpp<br>
> URL: <a href="http://llvm.org/viewvc/llvm-project/cfe/trunk/lib/Lex/PPCaching.cpp?rev=195799&r1=195798&r2=195799&view=diff" target="_blank">http://llvm.org/viewvc/llvm-project/cfe/trunk/lib/Lex/PPCaching.cpp?rev=195799&r1=195798&r2=195799&view=diff</a><br>
> ==============================================================================<br>
> --- cfe/trunk/lib/Lex/PPCaching.cpp (original)<br>
> +++ cfe/trunk/lib/Lex/PPCaching.cpp Tue Nov 26 19:27:40 2013<br>
> @@ -15,28 +15,28 @@<br>
> #include "clang/Lex/Preprocessor.h"<br>
> using namespace clang;<br>
><br>
> -/// EnableBacktrackAtThisPos - From the point that this method is called, and<br>
> -/// until CommitBacktrackedTokens() or Backtrack() is called, the Preprocessor<br>
> -/// keeps track of the lexed tokens so that a subsequent Backtrack() call will<br>
> -/// make the Preprocessor re-lex the same tokens.<br>
> -///<br>
> -/// Nested backtracks are allowed, meaning that EnableBacktrackAtThisPos can<br>
> -/// be called multiple times and CommitBacktrackedTokens/Backtrack calls will<br>
> -/// be combined with the EnableBacktrackAtThisPos calls in reverse order.<br>
> +// EnableBacktrackAtThisPos - From the point that this method is called, and<br>
> +// until CommitBacktrackedTokens() or Backtrack() is called, the Preprocessor<br>
> +// keeps track of the lexed tokens so that a subsequent Backtrack() call will<br>
> +// make the Preprocessor re-lex the same tokens.<br>
> +//<br>
> +// Nested backtracks are allowed, meaning that EnableBacktrackAtThisPos can<br>
> +// be called multiple times and CommitBacktrackedTokens/Backtrack calls will<br>
> +// be combined with the EnableBacktrackAtThisPos calls in reverse order.<br>
> void Preprocessor::EnableBacktrackAtThisPos() {<br>
> BacktrackPositions.push_back(CachedLexPos);<br>
> EnterCachingLexMode();<br>
> }<br>
><br>
> -/// CommitBacktrackedTokens - Disable the last EnableBacktrackAtThisPos call.<br>
> +// Disable the last EnableBacktrackAtThisPos call.<br>
> void Preprocessor::CommitBacktrackedTokens() {<br>
> assert(!BacktrackPositions.empty()<br>
> && "EnableBacktrackAtThisPos was not called!");<br>
> BacktrackPositions.pop_back();<br>
> }<br>
><br>
> -/// Backtrack - Make Preprocessor re-lex the tokens that were lexed since<br>
> -/// EnableBacktrackAtThisPos() was previously called.<br>
> +// Make Preprocessor re-lex the tokens that were lexed since<br>
> +// EnableBacktrackAtThisPos() was previously called.<br>
> void Preprocessor::Backtrack() {<br>
> assert(!BacktrackPositions.empty()<br>
> && "EnableBacktrackAtThisPos was not called!");<br>
> @@ -114,5 +114,4 @@ void Preprocessor::AnnotatePreviousCache<br>
> CachedLexPos = i;<br>
> return;<br>
> }<br>
> - }<br>
> -}<br>
> +<br>
><br>
> Modified: cfe/trunk/lib/Lex/PPDirectives.cpp<br>
> URL: <a href="http://llvm.org/viewvc/llvm-project/cfe/trunk/lib/Lex/PPDirectives.cpp?rev=195799&r1=195798&r2=195799&view=diff" target="_blank">http://llvm.org/viewvc/llvm-project/cfe/trunk/lib/Lex/PPDirectives.cpp?rev=195799&r1=195798&r2=195799&view=diff</a><br>
> ==============================================================================<br>
> --- cfe/trunk/lib/Lex/PPDirectives.cpp (original)<br>
> +++ cfe/trunk/lib/Lex/PPDirectives.cpp Tue Nov 26 19:27:40 2013<br>
> @@ -1327,21 +1327,20 @@ bool Preprocessor::GetIncludeFilenameSpe<br>
> return isAngled;<br>
> }<br>
><br>
> -/// \brief Handle cases where the \#include name is expanded from a macro<br>
> -/// as multiple tokens, which need to be glued together.<br>
> -///<br>
> -/// This occurs for code like:<br>
> -/// \code<br>
> -/// \#define FOO <a/b.h><br>
> -/// \#include FOO<br>
> -/// \endcode<br>
> -/// because in this case, "<a/b.h>" is returned as 7 tokens, not one.<br>
> -///<br>
> -/// This code concatenates and consumes tokens up to the '>' token. It returns<br>
> -/// false if the > was found, otherwise it returns true if it finds and consumes<br>
> -/// the EOD marker.<br>
> -bool Preprocessor::ConcatenateIncludeName(<br>
> - SmallString<128> &FilenameBuffer,<br>
> +// \brief Handle cases where the \#include name is expanded from a macro<br>
> +// as multiple tokens, which need to be glued together.<br>
> +//<br>
> +// This occurs for code like:<br>
> +// \code<br>
> +// \#define FOO <a/b.h><br>
> +// \#include FOO<br>
> +// \endcode<br>
> +// because in this case, "<a/b.h>" is returned as 7 tokens, not one.<br>
> +//<br>
> +// This code concatenates and consumes tokens up to the '>' token. It returns<br>
> +// false if the > was found, otherwise it returns true if it finds and consumes<br>
> +// the EOD marker.<br>
> +bool Preprocessor::ConcatenateIncludeName(SmallString<128> &FilenameBuffer,<br>
> SourceLocation &End) {<br>
> Token CurTok;<br>
><br>
><br>
><br>
> _______________________________________________<br>
> cfe-commits mailing list<br>
> <a href="mailto:cfe-commits@cs.uiuc.edu" target="_blank">cfe-commits@cs.uiuc.edu</a><br>
> <a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits" target="_blank">http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits</a><br>
_______________________________________________<br>
cfe-commits mailing list<br>
<a href="mailto:cfe-commits@cs.uiuc.edu" target="_blank">cfe-commits@cs.uiuc.edu</a><br>
<a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits" target="_blank">http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits</a><br>
</div></div></blockquote></div><br></div>
</div></div></blockquote></div><br></div></div>