Remove SourceManager::getBufferIdentifierForLoc

And tidy up doc comments for other methods that do or don't respect
'#sourceLocation'.

'getBufferIdentifierForLoc' is no longer useful: it doesn't
consistently return either the name of an actual buffer or the name of
a file suitable for diagnostics. As seen in the previous commit, all
remaining uses of it were wrong anyway. Remove it.

Author: jrose-apple

include/swift/Basic/SourceManager.h

@@ -39,7 +39,7 @@ class SourceManager {
   /// to speed up stats.
   mutable llvm::StringMap<clang::vfs::Status> StatusCache;
 
-  // #line directive handling.
+  // \c #sourceLocation directive handling.
   struct VirtualFile {
     CharSourceRange Range;
     std::string Name;
@@ -112,17 +112,17 @@ class SourceManager {
   /// Adds a memory buffer to the SourceManager, taking ownership of it.
   unsigned addNewSourceBuffer(std::unique_ptr<llvm::MemoryBuffer> Buffer);
 
-  /// Add a #line-defined virtual file region.
+  /// Add a \c #sourceLocation-defined virtual file region.
   ///
   /// By default, this region continues to the end of the buffer.
   ///
   /// \returns True if the new file was added, false if the file already exists.
   /// The name and line offset must match exactly in that case.
   ///
-  /// \sa closeVirtualFile.
+  /// \sa closeVirtualFile
   bool openVirtualFile(SourceLoc loc, StringRef name, int lineOffset);
 
-  /// Close a #line-defined virtual file region.
+  /// Close a \c #sourceLocation-defined virtual file region.
   void closeVirtualFile(SourceLoc end);
 
   /// Creates a copy of a \c MemoryBuffer and adds it to the \c SourceManager,
@@ -143,6 +143,11 @@ class SourceManager {
   /// Returns the identifier for the buffer with the given ID.
   ///
   /// \p BufferID must be a valid buffer ID.
+  ///
+  /// This should not be used for displaying information about the \e contents
+  /// of a buffer, since lines within the buffer may be marked as coming from
+  /// other files using \c #sourceLocation. Use #getDisplayNameForLoc instead
+  /// in that case.
   StringRef getIdentifierForBuffer(unsigned BufferID) const;
 
   /// \brief Returns a SourceRange covering the entire specified buffer.
@@ -175,26 +180,16 @@ class SourceManager {
   /// Returns a buffer identifier suitable for display to the user containing
   /// the given source location.
   ///
-  /// This respects #line directives and the 'use-external-names' directive in
-  /// VFS overlay files.
+  /// This respects \c #sourceLocation directives and the 'use-external-names'
+  /// directive in VFS overlay files. If you need an on-disk file name, use
+  /// #getIdentifierForBuffer instead.
   StringRef getDisplayNameForLoc(SourceLoc Loc) const;
 
-  /// Returns the identifier string for the buffer containing the given source
-  /// location.
-  ///
-  /// This respects #line directives.
-  StringRef getBufferIdentifierForLoc(SourceLoc Loc) const {
-    if (auto VFile = getVirtualFile(Loc))
-      return VFile->Name;
-    else
-      return getIdentifierForBuffer(findBufferContainingLoc(Loc));
-  }
-
   /// Returns the line and column represented by the given source location.
   ///
   /// If \p BufferID is provided, \p Loc must come from that source buffer.
   ///
-  /// This respects #line directives.
+  /// This respects \c #sourceLocation directives.
   std::pair<unsigned, unsigned>
   getLineAndColumn(SourceLoc Loc, unsigned BufferID = 0) const {
     assert(Loc.isValid());
@@ -209,7 +204,7 @@ class SourceManager {
   ///
   /// If \p BufferID is provided, \p Loc must come from that source buffer.
   ///
-  /// This does not respect #line directives.
+  /// This does not respect \c #sourceLocation directives.
   unsigned getLineNumber(SourceLoc Loc, unsigned BufferID = 0) const {
     assert(Loc.isValid());
     return LLVMSourceMgr.FindLineNumber(Loc.Value, BufferID);