From: James Dennett Date: Fri, 22 Jun 2012 05:46:07 +0000 (+0000) Subject: Documentation cleanup: X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=dc20169f3869ec7f4bfd4e62e81a21b4cb49e34d;p=clang Documentation cleanup: * Add \brief summaries; * Escape # characters in Doxygen comments; * Add \code...\endcode markup for code examples; * Add \verbatim...\endverbatim markup for grammar productions. git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@158976 91177308-0d34-0410-b5e6-96231b3b80d8 --- diff --git a/lib/Lex/PPDirectives.cpp b/lib/Lex/PPDirectives.cpp index 8f79796c58..b12eb81e6b 100644 --- a/lib/Lex/PPDirectives.cpp +++ b/lib/Lex/PPDirectives.cpp @@ -6,9 +6,10 @@ // License. See LICENSE.TXT for details. // //===----------------------------------------------------------------------===// -// -// This file implements # directive processing for the Preprocessor. -// +/// +/// \file +/// \brief Implements # directive processing for the Preprocessor. +/// //===----------------------------------------------------------------------===// #include "clang/Lex/Preprocessor.h" @@ -61,8 +62,8 @@ MacroInfo *Preprocessor::CloneMacroInfo(const MacroInfo &MacroToClone) { return MI; } -/// ReleaseMacroInfo - Release the specified MacroInfo. This memory will -/// be reused for allocating new MacroInfo objects. +/// \brief Release the specified MacroInfo to be reused for allocating +/// new MacroInfo objects. void Preprocessor::ReleaseMacroInfo(MacroInfo *MI) { MacroInfoChain *MIChain = (MacroInfoChain*) MI; if (MacroInfoChain *Prev = MIChain->Prev) { @@ -82,8 +83,8 @@ void Preprocessor::ReleaseMacroInfo(MacroInfo *MI) { MI->Destroy(); } -/// DiscardUntilEndOfDirective - Read and discard all tokens remaining on the -/// current line until the tok::eod token is found. +/// \brief Read and discard all tokens remaining on the current line until +/// the tok::eod token is found. void Preprocessor::DiscardUntilEndOfDirective() { Token Tmp; do { @@ -92,11 +93,13 @@ void Preprocessor::DiscardUntilEndOfDirective() { } while (Tmp.isNot(tok::eod)); } -/// ReadMacroName - Lex and validate a macro name, which occurs after a -/// #define or #undef. This sets the token kind to eod and discards the rest -/// of the macro line if the macro name is invalid. isDefineUndef is 1 if -/// this is due to a a #define, 2 if #undef directive, 0 if it is something -/// else (e.g. #ifdef). +/// \brief Lex and validate a macro name, which occurs after a +/// \#define or \#undef. +/// +/// This sets the token kind to eod and discards the rest +/// of the macro line if the macro name is invalid. \p isDefineUndef is 1 if +/// this is due to a a \#define, 2 if \#undef directive, 0 if it is something +/// else (e.g. \#ifdef). void Preprocessor::ReadMacroName(Token &MacroNameTok, char isDefineUndef) { // Read the token, don't allow macro expansion on it. LexUnexpandedToken(MacroNameTok); @@ -157,8 +160,9 @@ void Preprocessor::ReadMacroName(Token &MacroNameTok, char isDefineUndef) { return DiscardUntilEndOfDirective(); } -/// CheckEndOfDirective - Ensure that the next token is a tok::eod token. If -/// not, emit a diagnostic and consume up until the eod. If EnableMacros is +/// \brief Ensure that the next token is a tok::eod token. +/// +/// If not, emit a diagnostic and consume up until the eod. If EnableMacros is /// true, then we consider macros that expand to zero tokens as being ok. void Preprocessor::CheckEndOfDirective(const char *DirType, bool EnableMacros) { Token Tmp; @@ -191,14 +195,14 @@ void Preprocessor::CheckEndOfDirective(const char *DirType, bool EnableMacros) { -/// 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 +/// 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 /// FoundNonSkipPortion is true, then we have already emitted code for part of -/// this #if directive, so #else/#elif blocks should never be entered. If ElseOk -/// is true, 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. +/// this \#if directive, so \#else/\#elif blocks should never be entered. +/// If ElseOk is true, 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 Preprocessor::SkipExcludedConditionalBlock(SourceLocation IfTokenLoc, bool FoundNonSkipPortion, bool FoundElse, @@ -486,9 +490,6 @@ void Preprocessor::PTHSkipExcludedConditionalBlock() { } } -/// LookupFile - Given a "foo" or 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 ""). const FileEntry *Preprocessor::LookupFile( StringRef Filename, bool isAngled, @@ -808,10 +809,13 @@ static bool GetLineValue(Token &DigitTok, unsigned &Val, return false; } -/// HandleLineDirective - Handle #line directive: C99 6.10.4. The two -/// acceptable forms are: +/// \brief Handle a \#line directive: C99 6.10.4. +/// +/// The two acceptable forms are: +/// \verbatim /// # line digit-sequence /// # line digit-sequence "s-char-sequence" +/// \endverbatim void Preprocessor::HandleLineDirective(Token &Tok) { // Read the line # and string argument. Per C99 6.10.4p5, these tokens are // expanded. @@ -1154,7 +1158,7 @@ void Preprocessor::HandleMacroPrivateDirective(Token &Tok) { //===----------------------------------------------------------------------===// /// GetIncludeFilenameSpelling - Turn the specified lexer token into a fully -/// checked and spelled filename, e.g. as an operand of #include. This returns +/// 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 @@ -1198,11 +1202,14 @@ bool Preprocessor::GetIncludeFilenameSpelling(SourceLocation Loc, return isAngled; } -/// 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 -/// #include FOO +/// \brief 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: +/// \code +/// \#define FOO +/// \#include FOO +/// \endcode /// because in this case, "" is returned as 7 tokens, not one. /// /// This code concatenates and consumes tokens up to the '>' token. It returns @@ -1257,10 +1264,10 @@ bool Preprocessor::ConcatenateIncludeName( return true; } -/// HandleIncludeDirective - The "#include" tokens have just been read, read the -/// file to be included from the lexer, then include it! This is a common -/// routine with functionality shared between #include, #include_next and -/// #import. LookupFrom is set when this is a #include_next directive, it +/// HandleIncludeDirective - The "\#include" tokens have just been read, read +/// the file to be included from the lexer, then include it! This is a common +/// routine with functionality shared between \#include, \#include_next and +/// \#import. LookupFrom is set when this is a \#include_next directive, it /// specifies the file to start searching from. void Preprocessor::HandleIncludeDirective(SourceLocation HashLoc, Token &IncludeTok, @@ -1484,7 +1491,7 @@ void Preprocessor::HandleIncludeDirective(SourceLocation HashLoc, EnterSourceFile(FID, CurDir, FilenameTok.getLocation()); } -/// HandleIncludeNextDirective - Implements #include_next. +/// HandleIncludeNextDirective - Implements \#include_next. /// void Preprocessor::HandleIncludeNextDirective(SourceLocation HashLoc, Token &IncludeNextTok) { @@ -1507,7 +1514,7 @@ void Preprocessor::HandleIncludeNextDirective(SourceLocation HashLoc, return HandleIncludeDirective(HashLoc, IncludeNextTok, Lookup); } -/// HandleMicrosoftImportDirective - Implements #import for Microsoft Mode +/// HandleMicrosoftImportDirective - Implements \#import for Microsoft Mode void Preprocessor::HandleMicrosoftImportDirective(Token &Tok) { // The Microsoft #import directive takes a type library and generates header // files from it, and includes those. This is beyond the scope of what clang @@ -1521,7 +1528,7 @@ void Preprocessor::HandleMicrosoftImportDirective(Token &Tok) { DiscardUntilEndOfDirective(); } -/// HandleImportDirective - Implements #import. +/// HandleImportDirective - Implements \#import. /// void Preprocessor::HandleImportDirective(SourceLocation HashLoc, Token &ImportTok) { @@ -1653,7 +1660,7 @@ bool Preprocessor::ReadMacroDefinitionArgList(MacroInfo *MI, Token &Tok) { } } -/// HandleDefineDirective - Implements #define. This consumes the entire macro +/// HandleDefineDirective - Implements \#define. This consumes the entire macro /// line then lets the caller lex the next real token. void Preprocessor::HandleDefineDirective(Token &DefineTok) { ++NumDefined; @@ -1860,7 +1867,7 @@ void Preprocessor::HandleDefineDirective(Token &DefineTok) { Callbacks->MacroDefined(MacroNameTok, MI); } -/// HandleUndefDirective - Implements #undef. +/// HandleUndefDirective - Implements \#undef. /// void Preprocessor::HandleUndefDirective(Token &UndefTok) { ++NumUndefined; @@ -1901,10 +1908,10 @@ void Preprocessor::HandleUndefDirective(Token &UndefTok) { // Preprocessor Conditional Directive Handling. //===----------------------------------------------------------------------===// -/// HandleIfdefDirective - Implements the #ifdef/#ifndef directive. isIfndef is -/// true when this is a #ifndef directive. ReadAnyTokensBeforeDirective is true -/// if any tokens have been returned or pp-directives activated before this -/// #ifndef has been lexed. +/// HandleIfdefDirective - Implements the \#ifdef/\#ifndef directive. isIfndef +/// is true when this is a \#ifndef directive. ReadAnyTokensBeforeDirective is +/// true if any tokens have been returned or pp-directives activated before this +/// \#ifndef has been lexed. /// void Preprocessor::HandleIfdefDirective(Token &Result, bool isIfndef, bool ReadAnyTokensBeforeDirective) { @@ -1966,7 +1973,7 @@ void Preprocessor::HandleIfdefDirective(Token &Result, bool isIfndef, } } -/// HandleIfDirective - Implements the #if directive. +/// HandleIfDirective - Implements the \#if directive. /// void Preprocessor::HandleIfDirective(Token &IfToken, bool ReadAnyTokensBeforeDirective) { @@ -2003,7 +2010,7 @@ void Preprocessor::HandleIfDirective(Token &IfToken, } } -/// HandleEndifDirective - Implements the #endif directive. +/// HandleEndifDirective - Implements the \#endif directive. /// void Preprocessor::HandleEndifDirective(Token &EndifToken) { ++NumEndif; @@ -2029,7 +2036,7 @@ void Preprocessor::HandleEndifDirective(Token &EndifToken) { Callbacks->Endif(EndifToken.getLocation(), CondInfo.IfLoc); } -/// HandleElseDirective - Implements the #else directive. +/// HandleElseDirective - Implements the \#else directive. /// void Preprocessor::HandleElseDirective(Token &Result) { ++NumElse; @@ -2058,7 +2065,7 @@ void Preprocessor::HandleElseDirective(Token &Result) { /*FoundElse*/true, Result.getLocation()); } -/// HandleElifDirective - Implements the #elif directive. +/// HandleElifDirective - Implements the \#elif directive. /// void Preprocessor::HandleElifDirective(Token &ElifToken) { ++NumElse;