Clean up as many of the comments in Basic I can find to talk in terms of

'expansion' rather than 'instantiation' for macro source locations.

git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@136058 91177308-0d34-0410-b5e6-96231b3b80d8

include/clang/Basic/SourceLocation.h

@@ -71,14 +71,14 @@ private:
 ///
 /// Technically, a source location is simply an offset into the manager's view
 /// of the input source, which is all input buffers (including macro
-/// instantiations) concatenated in an effectively arbitrary order. The manager
-/// actually maintains two blocks of input buffers. One, starting at offset 0
-/// and growing upwards, contains all buffers from this module. The other,
+/// expansions) concatenated in an effectively arbitrary order. The manager
+/// actually maintains two blocks of input buffers. One, starting at offset
+/// 0 and growing upwards, contains all buffers from this module. The other,
 /// starting at the highest possible offset and growing downwards, contains
 /// buffers of loaded modules.
 ///
 /// In addition, one bit of SourceLocation is used for quick access to the
-/// information whether the location is in a file or a macro instantiation.
+/// information whether the location is in a file or a macro expansion.
 ///
 /// It is important that this type remains small. It is currently 32 bits wide.
 class SourceLocation {
@@ -339,8 +339,8 @@ public:
 
 /// PresumedLoc - This class represents an unpacked "presumed" location which
 /// can be presented to the user.  A 'presumed' location can be modified by
-/// #line and GNU line marker directives and is always the instantiation point
-/// of a normal location.
+/// #line and GNU line marker directives and is always the expansion point of
+/// a normal location.
 ///
 /// You can get a PresumedLoc from a SourceLocation with SourceManager.
 class PresumedLoc {

include/clang/Basic/SourceManager.h

@@ -106,8 +106,8 @@ namespace SrcMgr {
     unsigned getSize() const;
 
     /// getSizeBytesMapped - Returns the number of bytes actually mapped for
-    ///  this ContentCache.  This can be 0 if the MemBuffer was not actually
-    ///  instantiated.
+    /// this ContentCache. This can be 0 if the MemBuffer was not actually
+    /// expanded.
     unsigned getSizeBytesMapped() const;
     
     /// Returns the kind of memory used to back the memory buffer for
@@ -174,8 +174,8 @@ 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
-  /// instantiated from.  The main include file has an invalid IncludeLoc.
+  /// 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.
   ///
@@ -235,8 +235,8 @@ namespace SrcMgr {
 
     /// ExpansionLocStart/ExpansionLocEnd - In a macro expansion, these
     /// indicate the start and end of the expansion. In object-like macros,
-    /// these will be the same. In a function-like macro instantiation, the
-    /// start will be the identifier and the end will be the ')'. Finally, in
+    /// these will be the same. In a function-like macro expansion, the start
+    /// will be the identifier and the end will be the ')'. Finally, in
     /// macro-argument instantitions, the end will be 'SourceLocation()', an
     /// invalid location.
     unsigned ExpansionLocStart, ExpansionLocEnd;
@@ -309,7 +309,7 @@ namespace SrcMgr {
   /// ExpansionInfo.  SourceManager keeps an array of these objects, and
   /// they are uniquely identified by the FileID datatype.
   class SLocEntry {
-    unsigned Offset;   // low bit is set for instantiation info.
+    unsigned Offset;   // low bit is set for expansion info.
     union {
       FileInfo File;
       ExpansionInfo Expansion;
@@ -416,12 +416,12 @@ public:
 /// 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 instantiation locations.
-/// Spelling locations represent where the bytes corresponding to a token came
-/// from and instantiation locations represent where the location is in the
-/// user's view.  In the case of a macro expansion, for example, the spelling
-/// location indicates  where the expanded token came from and the instantiation
-/// location specifies where it was expanded.
+/// objects, turning them into either spelling or expansion locations. Spelling
+/// locations represent where the bytes corresponding to a token came from and
+/// expansion locations represent where the location is in the user's view. In
+/// the case of a macro expansion, for example, the spelling location indicates
+/// where the expanded token came from and the expansion location specifies
+/// where it was expanded.
 class SourceManager : public llvm::RefCountedBase<SourceManager> {
   /// \brief Diagnostic object.
   Diagnostic &Diag;
@@ -451,7 +451,7 @@ class SourceManager : public llvm::RefCountedBase<SourceManager> {
   /// \brief The table of SLocEntries that are local to this module.
   ///
   /// Positive FileIDs are indexes into this table. Entry 0 indicates an invalid
-  /// instantiation.
+  /// expansion.
   std::vector<SrcMgr::SLocEntry> LocalSLocEntryTable;
 
   /// \brief The table of SLocEntries that are loaded from other modules.
@@ -558,7 +558,7 @@ public:
   }
   
   //===--------------------------------------------------------------------===//
-  // Methods to create new FileID's and instantiations.
+  // Methods to create new FileID's and macro expansions.
   //===--------------------------------------------------------------------===//
 
   /// createFileID - Create a new FileID that represents the specified file
@@ -583,8 +583,8 @@ public:
 
   /// createMacroArgExpansionLoc - Return a new SourceLocation that encodes the
   /// fact that a token from SpellingLoc should actually be referenced from
-  /// ExpansionLoc, and that it represents the instantiation of a macro
-  /// argument into the function-like macro body.
+  /// ExpansionLoc, and that it represents the expansion of a macro argument
+  /// into the function-like macro body.
   SourceLocation createMacroArgExpansionLoc(SourceLocation Loc,
                                             SourceLocation ExpansionLoc,
                                             unsigned TokLength);
@@ -746,7 +746,7 @@ public:
   /// that make up the lexed token can be found.
   SourceLocation getSpellingLoc(SourceLocation Loc) const {
     // Handle the non-mapped case inline, defer to out of line code to handle
-    // instantiations.
+    // expansions.
     if (Loc.isFileID()) return Loc;
     return getSpellingLocSlowCase(Loc);
   }
@@ -765,9 +765,9 @@ public:
     return std::make_pair(FID, Loc.getOffset()-getSLocEntry(FID).getOffset());
   }
 
-  /// getDecomposedExpansionLoc - Decompose the specified location into a
-  /// raw FileID + Offset pair.  If the location is an instantiation record,
-  /// walk through it until we find the final location instantiated.
+  /// getDecomposedExpansionLoc - Decompose the specified location into a raw
+  /// FileID + Offset pair. If the location is an expansion record, walk
+  /// through it until we find the final location expanded.
   std::pair<FileID, unsigned>
   getDecomposedExpansionLoc(SourceLocation Loc) const {
     FileID FID = getFileID(Loc);
@@ -781,7 +781,7 @@ public:
   }
 
   /// getDecomposedSpellingLoc - Decompose the specified location into a raw
-  /// FileID + Offset pair.  If the location is an instantiation record, walk
+  /// FileID + Offset pair.  If the location is an expansion record, walk
   /// through it until we find its spelling record.
   std::pair<FileID, unsigned>
   getDecomposedSpellingLoc(SourceLocation Loc) const {
@@ -820,8 +820,8 @@ public:
 
   /// getColumnNumber - Return the column # for the specified file position.
   /// This is significantly cheaper to compute than the line number.  This
-  /// returns zero if the column number isn't known.  This may only be called on
-  /// a file sloc, so you must choose a spelling or instantiation location
+  /// returns zero if the column number isn't known.  This may only be called
+  /// on a file sloc, so you must choose a spelling or expansion location
   /// before calling this method.
   unsigned getColumnNumber(FileID FID, unsigned FilePos, 
                            bool *Invalid = 0) const;
@@ -860,8 +860,8 @@ public:
   /// or GNU line marker directives.  This provides a view on the data that a
   /// user should see in diagnostics, for example.
   ///
-  /// Note that a presumed location is always given as the instantiation point
-  /// of an instantiation location, not at the spelling location.
+  /// Note that a presumed location is always given as the expansion point of
+  /// an expansion location, not at the spelling location.
   ///
   /// \returns The presumed location of the specified SourceLocation. If the
   /// presumed location cannot be calculate (e.g., because \p Loc is invalid
@@ -1079,7 +1079,7 @@ private:
   }
   
   /// createExpansionLoc - Implements the common elements of storing an
-  /// instantiation info struct into the SLocEntry table and producing a source
+  /// expansion info struct into the SLocEntry table and producing a source
   /// location that refers to it.
   SourceLocation createExpansionLocImpl(const SrcMgr::ExpansionInfo &Expansion,
                                         unsigned TokLength,

lib/Basic/DiagnosticIDs.cpp

@@ -704,8 +704,8 @@ bool DiagnosticIDs::ProcessDiag(Diagnostic &Diag) const {
   }
 
   // If we have any Fix-Its, make sure that all of the Fix-Its point into
-  // source locations that aren't macro instantiations. If any point into
-  // macro instantiations, remove all of the Fix-Its.
+  // source locations that aren't macro expansions. If any point into macro
+  // expansions, remove all of the Fix-Its.
   for (unsigned I = 0, N = Diag.NumFixItHints; I != N; ++I) {
     const FixItHint &FixIt = Diag.FixItHints[I];
     if (FixIt.RemoveRange.isInvalid() ||

lib/Basic/SourceLocation.cpp

@@ -48,7 +48,7 @@ void SourceLocation::print(raw_ostream &OS, const SourceManager &SM)const{
       OS << "<invalid>";
       return;
     }
-    // The instantiation and spelling pos is identical for file locs.
+    // The macro expansion and spelling pos is identical for file locs.
     OS << PLoc.getFilename() << ':' << PLoc.getLine()
        << ':' << PLoc.getColumn();
     return;

lib/Basic/SourceManager.cpp

@@ -39,9 +39,8 @@ ContentCache::~ContentCache() {
     delete Buffer.getPointer();
 }
 
-/// getSizeBytesMapped - Returns the number of bytes actually mapped for
-///  this ContentCache.  This can be 0 if the MemBuffer was not actually
-///  instantiated.
+/// getSizeBytesMapped - Returns the number of bytes actually mapped for this
+/// ContentCache. This can be 0 if the MemBuffer was not actually expanded.
 unsigned ContentCache::getSizeBytesMapped() const {
   return Buffer.getPointer() ? Buffer.getPointer()->getBufferSize() : 0;
 }
@@ -401,7 +400,7 @@ void SourceManager::clearIDTables() {
   if (LineTable)
     LineTable->clear();
 
-  // Use up FileID #0 as an invalid instantiation.
+  // Use up FileID #0 as an invalid expansion.
   NextLocalOffset = 0;
   // The highest possible offset is 2^31-1, so CurrentLoadedOffset starts at
   // 2^31.
@@ -480,7 +479,7 @@ const llvm::MemoryBuffer *SourceManager::getFakeBufferForRecovery() const {
 }
 
 //===----------------------------------------------------------------------===//
-// Methods to create new FileID's and instantiations.
+// Methods to create new FileID's and macro expansions.
 //===----------------------------------------------------------------------===//
 
 /// createFileID - Create a new FileID for the specified ContentCache and
@@ -638,8 +637,8 @@ FileID SourceManager::getFileIDLocal(unsigned SLocOffset) const {
   assert(SLocOffset < NextLocalOffset && "Bad function choice");
 
   // After the first and second level caches, I see two common sorts of
-  // behavior: 1) a lot of searched FileID's are "near" the cached file location
-  // or are "near" the cached instantiation location.  2) others are just
+  // behavior: 1) a lot of searched FileID's are "near" the cached file
+  // location or are "near" the cached expansion location. 2) others are just
   // completely random and may be a very long way away.
   //
   // To handle this, we do a linear search for up to 8 steps to catch #1 quickly
@@ -667,8 +666,8 @@ FileID SourceManager::getFileIDLocal(unsigned SLocOffset) const {
     if (I->getOffset() <= SLocOffset) {
       FileID Res = FileID::get(int(I - LocalSLocEntryTable.begin()));
 
-      // If this isn't an instantiation, remember it.  We have good locality
-      // across FileID lookups.
+      // If this isn't an expansion, remember it.  We have good locality across
+      // FileID lookups.
       if (!I->isExpansion())
         LastFileIDLookup = Res;
       NumLinearScans += NumProbes+1;
@@ -811,8 +810,7 @@ SourceLocation SourceManager::getSpellingLocSlowCase(SourceLocation Loc) const {
 std::pair<FileID, unsigned>
 SourceManager::getDecomposedExpansionLocSlowCase(
                                              const SrcMgr::SLocEntry *E) const {
-  // If this is an instantiation record, walk through all the instantiation
-  // points.
+  // If this is an expansion record, walk through all the expansion points.
   FileID FID;
   SourceLocation Loc;
   unsigned Offset;
@@ -830,8 +828,7 @@ SourceManager::getDecomposedExpansionLocSlowCase(
 std::pair<FileID, unsigned>
 SourceManager::getDecomposedSpellingLocSlowCase(const SrcMgr::SLocEntry *E,
                                                 unsigned Offset) const {
-  // If this is an instantiation record, walk through all the instantiation
-  // points.
+  // If this is an expansion record, walk through all the expansion points.
   FileID FID;
   SourceLocation Loc;
   do {
@@ -857,11 +854,11 @@ SourceLocation SourceManager::getImmediateSpellingLoc(SourceLocation Loc) const{
 }
 
 
-/// getImmediateExpansionRange - Loc is required to be an instantiation
-/// location.  Return the start/end of the instantiation information.
+/// getImmediateExpansionRange - Loc is required to be an expansion location.
+/// Return the start/end of the expansion information.
 std::pair<SourceLocation,SourceLocation>
 SourceManager::getImmediateExpansionRange(SourceLocation Loc) const {
-  assert(Loc.isMacroID() && "Not an instantiation loc!");
+  assert(Loc.isMacroID() && "Not a macro expansion loc!");
   const ExpansionInfo &Expansion = getSLocEntry(getFileID(Loc)).getExpansion();
   return Expansion.getExpansionLocRange();
 }
@@ -875,7 +872,7 @@ SourceManager::getExpansionRange(SourceLocation Loc) const {
   std::pair<SourceLocation,SourceLocation> Res =
     getImmediateExpansionRange(Loc);
 
-  // Fully resolve the start and end locations to their ultimate instantiation
+  // Fully resolve the start and end locations to their ultimate expansion
   // points.
   while (!Res.first.isFileID())
     Res.first = getImmediateExpansionRange(Res.first).first;
@@ -1217,12 +1214,12 @@ const char *SourceManager::getBufferName(SourceLocation Loc,
 /// or GNU line marker directives.  This provides a view on the data that a
 /// user should see in diagnostics, for example.
 ///
-/// Note that a presumed location is always given as the instantiation point
-/// of an instantiation location, not at the spelling location.
+/// Note that a presumed location is always given as the expansion point of an
+/// expansion location, not at the spelling location.
 PresumedLoc SourceManager::getPresumedLoc(SourceLocation Loc) const {
   if (Loc.isInvalid()) return PresumedLoc();
 
-  // Presumed locations are always for instantiation points.
+  // Presumed locations are always for expansion points.
   std::pair<FileID, unsigned> LocInfo = getDecomposedExpansionLoc(Loc);
 
   bool Invalid = false;
@@ -1456,10 +1453,10 @@ SourceLocation SourceManager::getLocation(const FileEntry *SourceFile,
   return getLocForStartOfFile(FirstFID).getFileLocWithOffset(FilePos + Col - 1);
 }
 
-/// Given a decomposed source location, move it up the include/instantiation
-/// stack to the parent source location.  If this is possible, return the
-/// decomposed version of the parent in Loc and return false.  If Loc is the
-/// top-level entry, return true and don't modify it.
+/// Given a decomposed source location, move it up the include/expansion stack
+/// to the parent source location.  If this is possible, return the decomposed
+/// version of the parent in Loc and return false.  If Loc is the top-level
+/// entry, return true and don't modify it.
 static bool MoveUpIncludeHierarchy(std::pair<FileID, unsigned> &Loc,
                                    const SourceManager &SM) {
   SourceLocation UpperLoc;
@@ -1486,10 +1483,10 @@ bool SourceManager::isBeforeInTranslationUnit(SourceLocation LHS,
   if (LHS == RHS)
     return false;
 
-  // If both locations are macro instantiations, the order of their offsets
-  // reflect the order that the tokens, pointed to by these locations, were
-  // instantiated (during parsing each token that is instantiated by a macro,
-  // expands the SLocEntries).
+  // If both locations are macro expansions, the order of their offsets reflect
+  // the order that the tokens, pointed to by these locations, were expanded
+  // (during parsing each token that is expanded by a macro, expands the
+  // SLocEntries).
 
   std::pair<FileID, unsigned> LOffs = getDecomposedLoc(LHS);
   std::pair<FileID, unsigned> ROffs = getDecomposedLoc(RHS);