From c351d9837ea1d0b04842497e76c76125426a982c Mon Sep 17 00:00:00 2001 From: James Dennett Date: Fri, 15 Jun 2012 21:59:54 +0000 Subject: [PATCH] Documentation cleanup: * Escaped # characters in Doxygen comments; * Added Doxygen markup (\brief, \code, \file, \namespace). git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@158557 91177308-0d34-0410-b5e6-96231b3b80d8 --- include/clang/Basic/SourceManager.h | 65 +++++++++++++++++------------ 1 file changed, 38 insertions(+), 27 deletions(-) diff --git a/include/clang/Basic/SourceManager.h b/include/clang/Basic/SourceManager.h index 5a0db9a109..22d4ec737b 100644 --- a/include/clang/Basic/SourceManager.h +++ b/include/clang/Basic/SourceManager.h @@ -40,15 +40,20 @@ class LangOptions; class ASTWriter; class ASTReader; +/// \file /// There are three different types of locations in a file: a spelling /// location, an expansion location, and a presumed location. /// /// Given an example of: +/// \code /// #define min(x, y) x < y ? x : y +/// \endcode /// /// and then later on a use of min: +/// \code /// #line 17 /// return min(a, b); +/// \endcode /// /// The expansion location is the line in the source code where the macro /// was expanded (the return statement), the spelling location is the @@ -56,7 +61,8 @@ class ASTReader; /// and the presumed location is where the line directive states that /// the line is 17, or any other line. -/// SrcMgr - Public enums and private classes that are part of the +/// \namespace SrcMgr +/// \brief Public enums and private classes that are part of the /// SourceManager implementation. /// namespace SrcMgr { @@ -64,7 +70,7 @@ namespace SrcMgr { /// holds normal user code, system code, or system code which is implicitly /// 'extern "C"' in C++ mode. Entire directories can be tagged with this /// (this is maintained by DirectoryLookup and friends) as can specific - /// FileInfos when a #pragma system_header is seen or various other cases. + /// FileInfos when a \#pragma system_header is seen or various other cases. /// enum CharacteristicKind { C_User, C_System, C_ExternCSystem @@ -202,24 +208,24 @@ namespace SrcMgr { /// that it represents and include stack information. /// /// Each FileInfo has include stack information, indicating where it came - /// from. This information encodes the #include chain that a token was + /// from. This information encodes the \#include chain that a token was /// expanded from. The main include file has an invalid IncludeLoc. /// /// FileInfos contain a "ContentCache *", with the contents of the file. /// class FileInfo { - /// IncludeLoc - The location of the #include that brought in this file. - /// This is an invalid SLOC for the main file (top of the #include chain). + /// IncludeLoc - The location of the \#include that brought in this file. + /// This is an invalid SLOC for the main file (top of the \#include chain). unsigned IncludeLoc; // Really a SourceLocation /// \brief Number of FileIDs (files and macros) that were created during - /// preprocessing of this #include, including this SLocEntry. + /// preprocessing of this \#include, including this SLocEntry. /// Zero means the preprocessor didn't provide such info for this SLocEntry. unsigned NumCreatedFIDs; - /// Data - This contains the ContentCache* and the bits indicating the - /// characteristic of the file and whether it has #line info, all bitmangled - /// together. + /// \brief Contains the ContentCache* and the bits indicating the + /// characteristic of the file and whether it has \#line info, all + /// bitmangled together. uintptr_t Data; friend class clang::SourceManager; @@ -246,16 +252,15 @@ namespace SrcMgr { return reinterpret_cast(Data & ~7UL); } - /// getCharacteristic - Return whether this is a system header or not. + /// \brief Return whether this is a system header or not. CharacteristicKind getFileCharacteristic() const { return (CharacteristicKind)(Data & 3); } - /// hasLineDirectives - Return true if this FileID has #line directives in - /// it. + /// \brief Return true if this FileID has \#line directives in it. bool hasLineDirectives() const { return (Data & 4) != 0; } - /// setHasLineDirectives - Set the flag that indicates that this FileID has + /// \brief Set the flag that indicates that this FileID has /// line table entries associated with it. void setHasLineDirectives() { Data |= 4; @@ -415,13 +420,13 @@ class IsBeforeInTranslationUnitCache { /// to compare macro expansion locations. bool IsLQFIDBeforeRQFID; - /// CommonFID - This is the file found in common between the two #include - /// traces. It is the nearest common ancestor of the #include tree. + /// CommonFID - This is the file found in common between the two \#include + /// traces. It is the nearest common ancestor of the \#include tree. FileID CommonFID; /// L/R CommonOffset - This is the offset of the previous query in CommonFID. - /// Usually, this represents the location of the #include for QueryFID, but if - /// LQueryFID is a parent of RQueryFID (or vise versa) then these can be a + /// Usually, this represents the location of the \#include for QueryFID, but + /// if LQueryFID is a parent of RQueryFID (or vice versa) then these can be a /// random token in the parent. unsigned LCommonOffset, RCommonOffset; public: @@ -476,7 +481,7 @@ public: /// \brief This class handles loading and caching of source files into memory. /// /// This object owns the MemoryBuffer objects for all of the loaded -/// files and assigns unique FileID's for each unique #include chain. +/// files and assigns unique FileID's for each unique \#include chain. /// /// The SourceManager can be queried for information about SourceLocation /// objects, turning them into either spelling or expansion locations. Spelling @@ -562,13 +567,15 @@ class SourceManager : public RefCountedBase { /// \brief An external source for source location entries. ExternalSLocEntrySource *ExternalSLocEntries; - /// LastFileIDLookup - This is a one-entry cache to speed up getFileID. + /// \brief This is a one-entry cache to speed up getFileID. + /// /// LastFileIDLookup records the last FileID looked up or created, because it /// is very common to look up many tokens from the same file. mutable FileID LastFileIDLookup; - /// LineTable - This holds information for #line directives. It is referenced - /// by indices from SLocEntryTable. + /// \brief Holds information for \#line directives. + /// + /// It is referenced by indices from SLocEntryTable. LineTableInfo *LineTable; /// LastLineNo - These ivars serve as a cache used in the getLineNumber @@ -578,7 +585,7 @@ class SourceManager : public RefCountedBase { mutable unsigned LastLineNoFilePos; mutable unsigned LastLineNoResult; - /// MainFileID - The file ID for the main source file of the translation unit. + /// \brief The file ID for the main source file of the translation unit. FileID MainFileID; /// \brief The file ID for the precompiled preamble there is one. @@ -678,7 +685,7 @@ public: //===--------------------------------------------------------------------===// /// createFileID - Create a new FileID that represents the specified file - /// being #included from the specified IncludePosition. This translates NULL + /// being \#included from the specified IncludePosition. This translates NULL /// into standard input. FileID createFileID(const FileEntry *SourceFile, SourceLocation IncludePos, SrcMgr::CharacteristicKind FileCharacter, @@ -1086,9 +1093,11 @@ public: unsigned getExpansionLineNumber(SourceLocation Loc, bool *Invalid = 0) const; unsigned getPresumedLineNumber(SourceLocation Loc, bool *Invalid = 0) const; - /// Return the filename or buffer identifier of the buffer the location is in. - /// Note that this name does not respect #line directives. Use getPresumedLoc - /// for normal clients. + /// \brief Return the filename or buffer identifier of the buffer the + /// location is in. + /// + /// Note that this name does not respect \#line directives. Use + /// getPresumedLoc for normal clients. const char *getBufferName(SourceLocation Loc, bool *Invalid = 0) const; /// getFileCharacteristic - return the file characteristic of the specified @@ -1096,13 +1105,15 @@ public: /// header, or an "implicit extern C" system header. /// /// This state can be modified with flags on GNU linemarker directives like: + /// \code /// # 4 "foo.h" 3 + /// \endcode /// which changes all source locations in the current file after that to be /// considered to be from a system header. SrcMgr::CharacteristicKind getFileCharacteristic(SourceLocation Loc) const; /// getPresumedLoc - This method returns the "presumed" location of a - /// SourceLocation specifies. A "presumed location" can be modified by #line + /// SourceLocation specifies. A "presumed location" can be modified by \#line /// or GNU line marker directives. This provides a view on the data that a /// user should see in diagnostics, for example. /// -- 2.40.0