Modernize doc comments for SourceMgr.

No functionality change.

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

include/llvm/Support/SourceMgr.h

@@ -30,7 +30,7 @@ namespace llvm {
   class Twine;
   class raw_ostream;
 
-/// SourceMgr - This owns the files read by a parser, handles include stacks,
+/// This owns the files read by a parser, handles include stacks,
 /// and handles diagnostic wrangling.
 class SourceMgr {
 public:
@@ -40,29 +40,27 @@ public:
     DK_Note
   };
 
-  /// DiagHandlerTy - Clients that want to handle their own diagnostics in a
+  /// Clients that want to handle their own diagnostics in a custom way can
-  /// custom way can register a function pointer+context as a diagnostic
+  /// register a function pointer+context as a diagnostic handler.
-  /// handler.  It gets called each time PrintMessage is invoked.
+  /// It gets called each time PrintMessage is invoked.
   typedef void (*DiagHandlerTy)(const SMDiagnostic &, void *Context);
 private:
   struct SrcBuffer {
-    /// Buffer - The memory buffer for the file.
+    /// The memory buffer for the file.
     MemoryBuffer *Buffer;
 
-    /// IncludeLoc - This is the location of the parent include, or null if at
+    /// This is the location of the parent include, or null if at the top level.
-    /// the top level.
     SMLoc IncludeLoc;
   };
 
-  /// Buffers - This is all of the buffers that we are reading from.
+  /// This is all of the buffers that we are reading from.
   std::vector<SrcBuffer> Buffers;
 
-  // IncludeDirectories - This is the list of directories we should search for
+  // This is the list of directories we should search for include files in.
-  // include files in.
   std::vector<std::string> IncludeDirectories;
 
-  /// LineNoCache - This is a cache for line number queries, its implementation
+  /// This is a cache for line number queries, its implementation is really
-  /// is really private to SourceMgr.cpp.
+  /// private to SourceMgr.cpp.
   mutable void *LineNoCache;
 
   DiagHandlerTy DiagHandler;
@@ -79,8 +77,8 @@ public:
     IncludeDirectories = Dirs;
   }
 
-  /// setDiagHandler - Specify a diagnostic handler to be invoked every time
+  /// Specify a diagnostic handler to be invoked every time PrintMessage is
-  /// PrintMessage is called. Ctx is passed into the handler when it is invoked.
+  /// called. \p Ctx is passed into the handler when it is invoked.
   void setDiagHandler(DiagHandlerTy DH, void *Ctx = nullptr) {
     DiagHandler = DH;
     DiagContext = Ctx;
@@ -108,8 +106,8 @@ public:
     return Buffers[i].IncludeLoc;
   }
 
-  /// AddNewSourceBuffer - Add a new source buffer to this source manager.  This
+  /// Add a new source buffer to this source manager. This takes ownership of
-  /// takes ownership of the memory buffer.
+  /// the memory buffer.
   size_t AddNewSourceBuffer(MemoryBuffer *F, SMLoc IncludeLoc) {
     SrcBuffer NB;
     NB.Buffer = F;
@@ -118,32 +116,34 @@ public:
     return Buffers.size() - 1;
   }
 
-  /// AddIncludeFile - Search for a file with the specified name in the current
+  /// Search for a file with the specified name in the current directory or in
-  /// directory or in one of the IncludeDirs.  If no file is found, this returns
+  /// one of the IncludeDirs.
-  /// ~0, otherwise it returns the buffer ID of the stacked file.
+  ///
-  /// The full path to the included file can be found in IncludedFile.
+  /// If no file is found, this returns ~0, otherwise it returns the buffer ID
+  /// of the stacked file. The full path to the included file can be found in
+  /// \p IncludedFile.
   size_t AddIncludeFile(const std::string &Filename, SMLoc IncludeLoc,
                         std::string &IncludedFile);
 
-  /// FindBufferContainingLoc - Return the ID of the buffer containing the
+  /// Return the ID of the buffer containing the specified location.
-  /// specified location, returning -1 if not found.
+  ///
+  /// -1 is returned if the buffer is not found.
   int FindBufferContainingLoc(SMLoc Loc) const;
 
-  /// FindLineNumber - Find the line number for the specified location in the
+  /// Find the line number for the specified location in the specified file.
-  /// specified file.  This is not a fast method.
+  /// This is not a fast method.
   unsigned FindLineNumber(SMLoc Loc, int BufferID = -1) const {
     return getLineAndColumn(Loc, BufferID).first;
   }
 
-  /// getLineAndColumn - Find the line and column number for the specified
+  /// Find the line and column number for the specified location in the
-  /// location in the specified file.  This is not a fast method.
+  /// specified file. This is not a fast method.
   std::pair<unsigned, unsigned>
     getLineAndColumn(SMLoc Loc, int BufferID = -1) const;
 
-  /// PrintMessage - Emit a message about the specified location with the
+  /// Emit a message about the specified location with the specified string.
-  /// specified string.
   ///
-  /// @param ShowColors - Display colored messages if output is a terminal and
+  /// \param ShowColors Display colored messages if output is a terminal and
   /// the default error handler is used.
   void PrintMessage(raw_ostream &OS, SMLoc Loc, DiagKind Kind,
                     const Twine &Msg,
@@ -157,21 +157,21 @@ public:
                     ArrayRef<SMFixIt> FixIts = None,
                     bool ShowColors = true) const;
 
-  /// GetMessage - Return an SMDiagnostic at the specified location with the
+  /// Return an SMDiagnostic at the specified location with the specified
-  /// specified string.
+  /// string.
   ///
-  /// @param Msg If non-null, the kind of message (e.g., "error") which is
+  /// \param Msg If non-null, the kind of message (e.g., "error") which is
   /// prefixed to the message.
   SMDiagnostic GetMessage(SMLoc Loc, DiagKind Kind, const Twine &Msg,
                           ArrayRef<SMRange> Ranges = None,
                           ArrayRef<SMFixIt> FixIts = None) const;
 
-  /// PrintIncludeStack - Prints the names of included files and the line of the
+  /// Prints the names of included files and the line of the file they were
-  /// file they were included from.  A diagnostic handler can use this before
+  /// included from. A diagnostic handler can use this before printing its
-  /// printing its custom formatted message.
+  /// custom formatted message.
   ///
-  /// @param IncludeLoc - The line of the include.
+  /// \param IncludeLoc The location of the include.
-  /// @param OS the raw_ostream to print on.
+  /// \param OS the raw_ostream to print on.
   void PrintIncludeStack(SMLoc IncludeLoc, raw_ostream &OS) const;
 };
 
@@ -208,8 +208,8 @@ public:
 };
 
 
-/// SMDiagnostic - Instances of this class encapsulate one diagnostic report,
+/// Instances of this class encapsulate one diagnostic report, allowing
-/// allowing printing to a raw_ostream as a caret diagnostic.
+/// printing to a raw_ostream as a caret diagnostic.
 class SMDiagnostic {
   const SourceMgr *SM;
   SMLoc Loc;

lib/Support/SourceMgr.cpp

@@ -49,9 +49,6 @@ SourceMgr::~SourceMgr() {
   }
 }
 
-/// AddIncludeFile - Search for a file with the specified name in the current
-/// directory or in one of the IncludeDirs.  If no file is found, this returns
-/// ~0, otherwise it returns the buffer ID of the stacked file.
 size_t SourceMgr::AddIncludeFile(const std::string &Filename,
                                  SMLoc IncludeLoc,
                                  std::string &IncludedFile) {
@@ -71,8 +68,6 @@ size_t SourceMgr::AddIncludeFile(const std::string &Filename,
 }
 
 
-/// FindBufferContainingLoc - Return the ID of the buffer containing the
-/// specified location, returning -1 if not found.
 int SourceMgr::FindBufferContainingLoc(SMLoc Loc) const {
   for (unsigned i = 0, e = Buffers.size(); i != e; ++i)
     if (Loc.getPointer() >= Buffers[i].Buffer->getBufferStart() &&
@@ -83,8 +78,6 @@ int SourceMgr::FindBufferContainingLoc(SMLoc Loc) const {
   return -1;
 }
 
-/// getLineAndColumn - Find the line and column number for the specified
-/// location in the specified file.  This is not a fast method.
 std::pair<unsigned, unsigned>
 SourceMgr::getLineAndColumn(SMLoc Loc, int BufferID) const {
   if (BufferID == -1) BufferID = FindBufferContainingLoc(Loc);
@@ -143,11 +136,6 @@ void SourceMgr::PrintIncludeStack(SMLoc IncludeLoc, raw_ostream &OS) const {
 }
 
 
-/// GetMessage - Return an SMDiagnostic at the specified location with the
-/// specified string.
-///
-/// @param Type - If non-null, the kind of message (e.g., "error") which is
-/// prefixed to the message.
 SMDiagnostic SourceMgr::GetMessage(SMLoc Loc, SourceMgr::DiagKind Kind,
                                    const Twine &Msg,
                                    ArrayRef<SMRange> Ranges,