[cfe-commits] r158557 - /cfe/trunk/include/clang/Basic/SourceManager.h
James Dennett
jdennett at google.com
Fri Jun 15 14:59:54 PDT 2012
Author: jdennett
Date: Fri Jun 15 16:59:54 2012
New Revision: 158557
URL: http://llvm.org/viewvc/llvm-project?rev=158557&view=rev
Log:
Documentation cleanup:
* Escaped # characters in Doxygen comments;
* Added Doxygen markup (\brief, \code, \file, \namespace).
Modified:
cfe/trunk/include/clang/Basic/SourceManager.h
Modified: cfe/trunk/include/clang/Basic/SourceManager.h
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Basic/SourceManager.h?rev=158557&r1=158556&r2=158557&view=diff
==============================================================================
--- cfe/trunk/include/clang/Basic/SourceManager.h (original)
+++ cfe/trunk/include/clang/Basic/SourceManager.h Fri Jun 15 16:59:54 2012
@@ -40,15 +40,20 @@
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 @@
/// 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 @@
/// 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 @@
/// 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 @@
return reinterpret_cast<const ContentCache*>(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 @@
/// 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 @@
/// \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 @@
/// \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 @@
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 @@
//===--------------------------------------------------------------------===//
/// 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 @@
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 @@
/// 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.
///
More information about the cfe-commits
mailing list