[clang][extract-api] Refactor ExtractAPI and improve docs

- The name SymbolGraph is inappropriate and confusing for the new library
  for clang-extract-api. Refactor and rename things to make it clear that
  ExtractAPI is the core functionality and SymbolGraph is one serializer
  for the API information.
- Add documentation comments to ExtractAPI classes and methods to improve
  readability and clearness of the ExtractAPI work.

Differential Revision: https://reviews.llvm.org/D122160

Author: zixu-w

clang/include/clang/SymbolGraph/API.h renamed to clang/include/clang/ExtractAPI/API.h

@@ -1,4 +1,4 @@
-//===- SymbolGraph/API.h ----------------------------------------*- C++ -*-===//
+//===- ExtractAPI/API.h -----------------------------------------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
@@ -7,18 +7,22 @@
 //===----------------------------------------------------------------------===//
 ///
 /// \file
-/// \brief Defines SymbolGraph API records.
+/// This file defines the APIRecord-based structs and the APISet class.
+///
+/// Clang ExtractAPI is a tool to collect API information from a given set of
+/// header files. The structures in this file describe data representations of
+/// the API information collected for various kinds of symbols.
 ///
 //===----------------------------------------------------------------------===//
 
-#ifndef LLVM_CLANG_SYMBOLGRAPH_API_H
-#define LLVM_CLANG_SYMBOLGRAPH_API_H
+#ifndef LLVM_CLANG_EXTRACTAPI_API_H
+#define LLVM_CLANG_EXTRACTAPI_API_H
 
 #include "clang/AST/Decl.h"
 #include "clang/AST/RawCommentList.h"
 #include "clang/Basic/SourceLocation.h"
-#include "clang/SymbolGraph/AvailabilityInfo.h"
-#include "clang/SymbolGraph/DeclarationFragments.h"
+#include "clang/ExtractAPI/AvailabilityInfo.h"
+#include "clang/ExtractAPI/DeclarationFragments.h"
 #include "llvm/ADT/MapVector.h"
 #include "llvm/ADT/StringRef.h"
 #include "llvm/ADT/Triple.h"
@@ -27,18 +31,43 @@
 #include <memory>
 
 namespace clang {
-namespace symbolgraph {
+namespace extractapi {
 
+/// DocComment is a vector of RawComment::CommentLine.
+///
+/// Each line represents one line of striped documentation comment,
+/// with source range information. This simplifies calculating the source
+/// location of a character in the doc comment for pointing back to the source
+/// file.
+/// e.g.
+/// \code
+///   /// This is a documentation comment
+///       ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~'  First line.
+///   ///     with multiple lines.
+///       ^~~~~~~~~~~~~~~~~~~~~~~'         Second line.
+/// \endcode
 using DocComment = std::vector<RawComment::CommentLine>;
 
+/// The base representation of an API record. Holds common symbol information.
 struct APIRecord {
   StringRef Name;
   StringRef USR;
   PresumedLoc Location;
   AvailabilityInfo Availability;
   LinkageInfo Linkage;
+
+  /// Documentation comment lines attached to this symbol declaration.
   DocComment Comment;
+
+  /// Declaration fragments of this symbol declaration.
   DeclarationFragments Declaration;
+
+  /// SubHeading provides a more detailed representation than the plain
+  /// declaration name.
+  ///
+  /// SubHeading is an array of declaration fragments of tagged declaration
+  /// name, with potentially more tokens (for example the \c +/- symbol for
+  /// Objective-C class/instance methods).
   DeclarationFragments SubHeading;
 
   /// Discriminator for LLVM-style RTTI (dyn_cast<> et al.)
@@ -66,14 +95,18 @@ struct APIRecord {
   virtual ~APIRecord() = 0;
 };
 
+/// The kind of a global record.
 enum class GVKind : uint8_t {
   Unknown = 0,
   Variable = 1,
   Function = 2,
 };
 
+/// This holds information associated with global variables or functions.
 struct GlobalRecord : APIRecord {
   GVKind GlobalKind;
+
+  /// The function signature of the record if it is a function.
   FunctionSignature Signature;
 
   GlobalRecord(GVKind Kind, StringRef Name, StringRef USR, PresumedLoc Loc,
@@ -87,40 +120,52 @@ struct GlobalRecord : APIRecord {
   static bool classof(const APIRecord *Record) {
     return Record->getKind() == RK_Global;
   }
+
+private:
+  virtual void anchor();
 };
 
+/// APISet holds the set of API records collected from given inputs.
 class APISet {
 public:
-  APISet(const llvm::Triple &Target, const LangOptions &LangOpts)
-      : Target(Target), LangOpts(LangOpts) {}
-
-  const llvm::Triple &getTarget() const { return Target; }
-  const LangOptions &getLangOpts() const { return LangOpts; }
-
+  /// Create and add a GlobalRecord of kind \p Kind into the API set.
+  ///
+  /// Note: the caller is responsible for keeping the StringRef \p Name and
+  /// \p USR alive. APISet::copyString provides a way to copy strings into
+  /// APISet itself, and APISet::recordUSR(const Decl *D) is a helper method
+  /// to generate the USR for \c D and keep it alive in APISet.
   GlobalRecord *addGlobal(GVKind Kind, StringRef Name, StringRef USR,
                           PresumedLoc Loc, const AvailabilityInfo &Availability,
                           LinkageInfo Linkage, const DocComment &Comment,
                           DeclarationFragments Declaration,
                           DeclarationFragments SubHeading,
                           FunctionSignature Signature);
 
+  /// Create and add a global variable record into the API set.
+  ///
+  /// Note: the caller is responsible for keeping the StringRef \p Name and
+  /// \p USR alive. APISet::copyString provides a way to copy strings into
+  /// APISet itself, and APISet::recordUSR(const Decl *D) is a helper method
+  /// to generate the USR for \c D and keep it alive in APISet.
   GlobalRecord *addGlobalVar(StringRef Name, StringRef USR, PresumedLoc Loc,
                              const AvailabilityInfo &Availability,
                              LinkageInfo Linkage, const DocComment &Comment,
                              DeclarationFragments Declaration,
                              DeclarationFragments SubHeading);
 
+  /// Create and add a function record into the API set.
+  ///
+  /// Note: the caller is responsible for keeping the StringRef \p Name and
+  /// \p USR alive. APISet::copyString provides a way to copy strings into
+  /// APISet itself, and APISet::recordUSR(const Decl *D) is a helper method
+  /// to generate the USR for \c D and keep it alive in APISet.
   GlobalRecord *addFunction(StringRef Name, StringRef USR, PresumedLoc Loc,
                             const AvailabilityInfo &Availability,
                             LinkageInfo Linkage, const DocComment &Comment,
                             DeclarationFragments Declaration,
                             DeclarationFragments SubHeading,
                             FunctionSignature Signature);
 
-  StringRef recordUSR(const Decl *D);
-  StringRef copyString(StringRef String, llvm::BumpPtrAllocator &Allocator);
-  StringRef copyString(StringRef String);
-
 private:
   /// \brief A custom deleter used for ``std::unique_ptr`` to APIRecords stored
   /// in the BumpPtrAllocator.
@@ -138,20 +183,45 @@ class APISet {
   using APIRecordUniquePtr =
       std::unique_ptr<T, UniquePtrBumpPtrAllocatorDeleter<T>>;
 
+  /// A map to store the set of GlobalRecord%s with the declaration name as the
+  /// key.
   using GlobalRecordMap =
       llvm::MapVector<StringRef, APIRecordUniquePtr<GlobalRecord>>;
 
+  /// Get the target triple for the ExtractAPI invocation.
+  const llvm::Triple &getTarget() const { return Target; }
+
+  /// Get the language options used to parse the APIs.
+  const LangOptions &getLangOpts() const { return LangOpts; }
+
   const GlobalRecordMap &getGlobals() const { return Globals; }
 
+  /// Generate and store the USR of declaration \p D.
+  ///
+  /// Note: The USR string is stored in and owned by Allocator.
+  ///
+  /// \returns a StringRef of the generated USR string.
+  StringRef recordUSR(const Decl *D);
+
+  /// Copy \p String into the Allocator in this APISet.
+  ///
+  /// \returns a StringRef of the copied string in APISet::Allocator.
+  StringRef copyString(StringRef String);
+
+  APISet(const llvm::Triple &Target, const LangOptions &LangOpts)
+      : Target(Target), LangOpts(LangOpts) {}
+
 private:
+  /// BumpPtrAllocator to store APIRecord%s and generated/copied strings.
   llvm::BumpPtrAllocator Allocator;
+
   const llvm::Triple Target;
   const LangOptions LangOpts;
 
   GlobalRecordMap Globals;
 };
 
-} // namespace symbolgraph
+} // namespace extractapi
 } // namespace clang
 
-#endif // LLVM_CLANG_SYMBOLGRAPH_API_H
+#endif // LLVM_CLANG_EXTRACTAPI_API_H

clang/include/clang/SymbolGraph/AvailabilityInfo.h renamed to clang/include/clang/ExtractAPI/AvailabilityInfo.h

@@ -1,4 +1,4 @@
-//===- SymbolGraph/AvailabilityInfo.h - Availability Info -------*- C++ -*-===//
+//===- ExtractAPI/AvailabilityInfo.h - Availability Info --------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
@@ -7,12 +7,13 @@
 //===----------------------------------------------------------------------===//
 ///
 /// \file
-/// \brief Defines the Availability Info for a declaration.
+/// This file defines the AvailabilityInfo struct that collects availability
+/// attributes of a symbol.
 ///
 //===----------------------------------------------------------------------===//
 
-#ifndef LLVM_CLANG_SYMBOLGRAPH_AVAILABILITY_INFO_H
-#define LLVM_CLANG_SYMBOLGRAPH_AVAILABILITY_INFO_H
+#ifndef LLVM_CLANG_EXTRACTAPI_AVAILABILITY_INFO_H
+#define LLVM_CLANG_EXTRACTAPI_AVAILABILITY_INFO_H
 
 #include "llvm/Support/Error.h"
 #include "llvm/Support/VersionTuple.h"
@@ -21,8 +22,9 @@
 using llvm::VersionTuple;
 
 namespace clang {
-namespace symbolgraph {
+namespace extractapi {
 
+/// Stores availability attributes of a symbol.
 struct AvailabilityInfo {
   VersionTuple Introduced;
   VersionTuple Deprecated;
@@ -31,21 +33,31 @@ struct AvailabilityInfo {
   bool UnconditionallyDeprecated{false};
   bool UnconditionallyUnavailable{false};
 
-  explicit AvailabilityInfo(bool Unavailable = false)
-      : Unavailable(Unavailable) {}
-
-  AvailabilityInfo(VersionTuple I, VersionTuple D, VersionTuple O, bool U,
-                   bool UD, bool UU)
-      : Introduced(I), Deprecated(D), Obsoleted(O), Unavailable(U),
-        UnconditionallyDeprecated(UD), UnconditionallyUnavailable(UU) {}
-
+  /// Determine if this AvailabilityInfo represents the default availability.
   bool isDefault() const { return *this == AvailabilityInfo(); }
+
+  /// Check if the symbol is unavailable.
   bool isUnavailable() const { return Unavailable; }
+
+  /// Check if the symbol is unconditionally deprecated.
+  ///
+  /// i.e. \code __attribute__((deprecated)) \endcode
   bool isUnconditionallyDeprecated() const { return UnconditionallyDeprecated; }
+
+  /// Check if the symbol is unconditionally unavailable.
+  ///
+  /// i.e. \code __attribute__((unavailable)) \endcode
   bool isUnconditionallyUnavailable() const {
     return UnconditionallyUnavailable;
   }
 
+  AvailabilityInfo() = default;
+
+  AvailabilityInfo(VersionTuple I, VersionTuple D, VersionTuple O, bool U,
+                   bool UD, bool UU)
+      : Introduced(I), Deprecated(D), Obsoleted(O), Unavailable(U),
+        UnconditionallyDeprecated(UD), UnconditionallyUnavailable(UU) {}
+
   friend bool operator==(const AvailabilityInfo &Lhs,
                          const AvailabilityInfo &Rhs);
 };
@@ -60,7 +72,7 @@ inline bool operator==(const AvailabilityInfo &Lhs,
                   Rhs.UnconditionallyUnavailable);
 }
 
-} // namespace symbolgraph
+} // namespace extractapi
 } // namespace clang
 
-#endif // LLVM_CLANG_SYMBOLGRAPH_AVAILABILITY_INFO_H
+#endif // LLVM_CLANG_EXTRACTAPI_AVAILABILITY_INFO_H