[clang][extract-api] Add enum support

Add support for enum records
- Add `EnumConstantRecord` and `EnumRecord` to store API information for
  enums
- Implement `VisitEnumDecl` in `ExtractAPIVisitor`
- Implement serializatin for enum records and `MemberOf` relationship
- Add test case for enum records
- Few other improvements

Depends on D122160

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

Author: zixu-w

clang/include/clang/ExtractAPI/API.h

@@ -30,6 +30,25 @@
 #include "llvm/Support/Casting.h"
 #include <memory>
 
+namespace {
+
+/// \brief A custom deleter used for ``std::unique_ptr`` to APIRecords stored
+/// in the BumpPtrAllocator.
+///
+/// \tparam T the exact type of the APIRecord subclass.
+template <typename T> struct UniquePtrBumpPtrAllocatorDeleter {
+  void operator()(T *Instance) { Instance->~T(); }
+};
+
+/// A unique pointer to an APIRecord stored in the BumpPtrAllocator.
+///
+/// \tparam T the exact type of the APIRecord subclass.
+template <typename T>
+using APIRecordUniquePtr =
+    std::unique_ptr<T, UniquePtrBumpPtrAllocatorDeleter<T>>;
+
+} // anonymous namespace
+
 namespace clang {
 namespace extractapi {
 
@@ -73,6 +92,8 @@ struct APIRecord {
   /// Discriminator for LLVM-style RTTI (dyn_cast<> et al.)
   enum RecordKind {
     RK_Global,
+    RK_EnumConstant,
+    RK_Enum,
   };
 
 private:
@@ -125,6 +146,36 @@ struct GlobalRecord : APIRecord {
   virtual void anchor();
 };
 
+/// This holds information associated with enum constants.
+struct EnumConstantRecord : APIRecord {
+  EnumConstantRecord(StringRef Name, StringRef USR, PresumedLoc Loc,
+                     const AvailabilityInfo &Availability,
+                     const DocComment &Comment,
+                     DeclarationFragments Declaration,
+                     DeclarationFragments SubHeading)
+      : APIRecord(RK_EnumConstant, Name, USR, Loc, Availability,
+                  LinkageInfo::none(), Comment, Declaration, SubHeading) {}
+
+  static bool classof(const APIRecord *Record) {
+    return Record->getKind() == RK_EnumConstant;
+  }
+};
+
+/// This holds information associated with enums.
+struct EnumRecord : APIRecord {
+  SmallVector<APIRecordUniquePtr<EnumConstantRecord>> Constants;
+
+  EnumRecord(StringRef Name, StringRef USR, PresumedLoc Loc,
+             const AvailabilityInfo &Availability, const DocComment &Comment,
+             DeclarationFragments Declaration, DeclarationFragments SubHeading)
+      : APIRecord(RK_Enum, Name, USR, Loc, Availability, LinkageInfo::none(),
+                  Comment, Declaration, SubHeading) {}
+
+  static bool classof(const APIRecord *Record) {
+    return Record->getKind() == RK_Enum;
+  }
+};
+
 /// APISet holds the set of API records collected from given inputs.
 class APISet {
 public:
@@ -166,35 +217,49 @@ class APISet {
                             DeclarationFragments SubHeading,
                             FunctionSignature Signature);
 
-private:
-  /// \brief A custom deleter used for ``std::unique_ptr`` to APIRecords stored
-  /// in the BumpPtrAllocator.
+  /// Create and add an enum constant record into the API set.
   ///
-  /// \tparam T the exact type of the APIRecord subclass.
-  template <typename T> struct UniquePtrBumpPtrAllocatorDeleter {
-    void operator()(T *Instance) { Instance->~T(); }
-  };
-
-public:
-  /// A unique pointer to an APIRecord stored in the BumpPtrAllocator.
+  /// 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.
+  EnumConstantRecord *addEnumConstant(EnumRecord *Enum, StringRef Name,
+                                      StringRef USR, PresumedLoc Loc,
+                                      const AvailabilityInfo &Availability,
+                                      const DocComment &Comment,
+                                      DeclarationFragments Declaration,
+                                      DeclarationFragments SubHeading);
+
+  /// Create and add an enum record into the API set.
   ///
-  /// \tparam T the exact type of the APIRecord subclass.
-  template <typename T>
-  using APIRecordUniquePtr =
-      std::unique_ptr<T, UniquePtrBumpPtrAllocatorDeleter<T>>;
+  /// 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.
+  EnumRecord *addEnum(StringRef Name, StringRef USR, PresumedLoc Loc,
+                      const AvailabilityInfo &Availability,
+                      const DocComment &Comment,
+                      DeclarationFragments Declaration,
+                      DeclarationFragments SubHeading);
 
   /// A map to store the set of GlobalRecord%s with the declaration name as the
   /// key.
   using GlobalRecordMap =
       llvm::MapVector<StringRef, APIRecordUniquePtr<GlobalRecord>>;
 
+  /// A map to store the set of EnumRecord%s with the declaration name as the
+  /// key.
+  using EnumRecordMap =
+      llvm::MapVector<StringRef, APIRecordUniquePtr<EnumRecord>>;
+
   /// 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; }
+  const EnumRecordMap &getEnums() const { return Enums; }
 
   /// Generate and store the USR of declaration \p D.
   ///
@@ -219,6 +284,7 @@ class APISet {
   const LangOptions LangOpts;
 
   GlobalRecordMap Globals;
+  EnumRecordMap Enums;
 };
 
 } // namespace extractapi

clang/include/clang/ExtractAPI/DeclarationFragments.h

@@ -188,6 +188,14 @@ class DeclarationFragmentsBuilder {
   /// Build DeclarationFragments for a function declaration FunctionDecl.
   static DeclarationFragments getFragmentsForFunction(const FunctionDecl *);
 
+  /// Build DeclarationFragments for an enum constant declaration
+  /// EnumConstantDecl.
+  static DeclarationFragments
+  getFragmentsForEnumConstant(const EnumConstantDecl *);
+
+  /// Build DeclarationFragments for an enum declaration EnumDecl.
+  static DeclarationFragments getFragmentsForEnum(const EnumDecl *);
+
   /// Build sub-heading fragments for a NamedDecl.
   static DeclarationFragments getSubHeading(const NamedDecl *);
 

clang/include/clang/ExtractAPI/Serialization/SymbolGraphSerializer.h

@@ -56,6 +56,17 @@ class SymbolGraphSerializer : public APISerializer {
   /// write out the serialized JSON object to \p os.
   void serialize(raw_ostream &os) override;
 
+  /// The kind of a relationship between two symbols.
+  enum RelationshipKind {
+    /// The source symbol is a member of the target symbol.
+    /// For example enum constants are members of the enum, class/instance
+    /// methods are members of the class, etc.
+    MemberOf,
+  };
+
+  /// Get the string representation of the relationship kind.
+  static StringRef getRelationshipString(RelationshipKind Kind);
+
 private:
   /// Synthesize the metadata section of the Symbol Graph format.
   ///
@@ -86,9 +97,19 @@ class SymbolGraphSerializer : public APISerializer {
   /// containing common symbol information of \p Record.
   Optional<Object> serializeAPIRecord(const APIRecord &Record) const;
 
+  /// Serialize the \p Kind relationship between \p Source and \p Target.
+  ///
+  /// Record the relationship between the two symbols in
+  /// SymbolGraphSerializer::Relationships.
+  void serializeRelationship(RelationshipKind Kind, const APIRecord &Source,
+                             const APIRecord &Target);
+
   /// Serialize a global record.
   void serializeGlobalRecord(const GlobalRecord &Record);
 
+  /// Serialize an enum record.
+  void serializeEnumRecord(const EnumRecord &Record);
+
 public:
   SymbolGraphSerializer(const APISet &API, StringRef ProductName,
                         APISerializerOption Options = {})

clang/lib/ExtractAPI/API.cpp

@@ -59,6 +59,31 @@ APISet::addFunction(StringRef Name, StringRef USR, PresumedLoc Loc,
                    Comment, Fragments, SubHeading, Signature);
 }
 
+EnumConstantRecord *APISet::addEnumConstant(
+    EnumRecord *Enum, StringRef Name, StringRef USR, PresumedLoc Loc,
+    const AvailabilityInfo &Availability, const DocComment &Comment,
+    DeclarationFragments Declaration, DeclarationFragments SubHeading) {
+  auto Record =
+      APIRecordUniquePtr<EnumConstantRecord>(new (Allocator) EnumConstantRecord{
+          Name, USR, Loc, Availability, Comment, Declaration, SubHeading});
+  return Enum->Constants.emplace_back(std::move(Record)).get();
+}
+
+EnumRecord *APISet::addEnum(StringRef Name, StringRef USR, PresumedLoc Loc,
+                            const AvailabilityInfo &Availability,
+                            const DocComment &Comment,
+                            DeclarationFragments Declaration,
+                            DeclarationFragments SubHeading) {
+  auto Result = Enums.insert({Name, nullptr});
+  if (Result.second) {
+    // Create the record if it does not already exist.
+    auto Record = APIRecordUniquePtr<EnumRecord>(new (Allocator) EnumRecord{
+        Name, USR, Loc, Availability, Comment, Declaration, SubHeading});
+    Result.first->second = std::move(Record);
+  }
+  return Result.first->second.get();
+}
+
 StringRef APISet::recordUSR(const Decl *D) {
   SmallString<128> USR;
   index::generateUSRForDecl(D, USR);

clang/lib/ExtractAPI/DeclarationFragments.cpp

@@ -401,6 +401,35 @@ DeclarationFragmentsBuilder::getFragmentsForFunction(const FunctionDecl *Func) {
   return Fragments;
 }
 
+DeclarationFragments DeclarationFragmentsBuilder::getFragmentsForEnumConstant(
+    const EnumConstantDecl *EnumConstDecl) {
+  DeclarationFragments Fragments;
+  return Fragments.append(EnumConstDecl->getName(),
+                          DeclarationFragments::FragmentKind::Identifier);
+}
+
+DeclarationFragments
+DeclarationFragmentsBuilder::getFragmentsForEnum(const EnumDecl *EnumDecl) {
+  // TODO: After we support typedef records, if there's a typedef for this enum
+  // just use the declaration fragments of the typedef decl.
+
+  DeclarationFragments Fragments, After;
+  Fragments.append("enum", DeclarationFragments::FragmentKind::Keyword);
+
+  if (!EnumDecl->getName().empty())
+    Fragments.appendSpace().append(
+        EnumDecl->getName(), DeclarationFragments::FragmentKind::Identifier);
+
+  QualType IntegerType = EnumDecl->getIntegerType();
+  if (!IntegerType.isNull())
+    Fragments.append(": ", DeclarationFragments::FragmentKind::Text)
+        .append(
+            getFragmentsForType(IntegerType, EnumDecl->getASTContext(), After))
+        .append(std::move(After));
+
+  return Fragments;
+}
+
 FunctionSignature
 DeclarationFragmentsBuilder::getFunctionSignature(const FunctionDecl *Func) {
   FunctionSignature Signature;

clang/lib/ExtractAPI/ExtractAPIConsumer.cpp

@@ -145,6 +145,40 @@ class ExtractAPIVisitor : public RecursiveASTVisitor<ExtractAPIVisitor> {
     return true;
   }
 
+  bool VisitEnumDecl(const EnumDecl *Decl) {
+    if (!Decl->isComplete())
+      return true;
+
+    // Skip forward declaration.
+    if (!Decl->isThisDeclarationADefinition())
+      return true;
+
+    // Collect symbol information.
+    StringRef Name = Decl->getName();
+    StringRef USR = API.recordUSR(Decl);
+    PresumedLoc Loc =
+        Context.getSourceManager().getPresumedLoc(Decl->getLocation());
+    AvailabilityInfo Availability = getAvailability(Decl);
+    DocComment Comment;
+    if (auto *RawComment = Context.getRawCommentForDeclNoCache(Decl))
+      Comment = RawComment->getFormattedLines(Context.getSourceManager(),
+                                              Context.getDiagnostics());
+
+    // Build declaration fragments and sub-heading for the enum.
+    DeclarationFragments Declaration =
+        DeclarationFragmentsBuilder::getFragmentsForEnum(Decl);
+    DeclarationFragments SubHeading =
+        DeclarationFragmentsBuilder::getSubHeading(Decl);
+
+    EnumRecord *EnumRecord = API.addEnum(Name, USR, Loc, Availability, Comment,
+                                         Declaration, SubHeading);
+
+    // Now collect information about the enumerators in this enum.
+    recordEnumConstants(EnumRecord, Decl->enumerators());
+
+    return true;
+  }
+
 private:
   /// Get availability information of the declaration \p D.
   AvailabilityInfo getAvailability(const Decl *D) const {
@@ -177,6 +211,33 @@ class ExtractAPIVisitor : public RecursiveASTVisitor<ExtractAPIVisitor> {
     return Availability;
   }
 
+  /// Collect API information for the enum constants and associate with the
+  /// parent enum.
+  void recordEnumConstants(EnumRecord *EnumRecord,
+                           const EnumDecl::enumerator_range Constants) {
+    for (const auto *Constant : Constants) {
+      // Collect symbol information.
+      StringRef Name = Constant->getName();
+      StringRef USR = API.recordUSR(Constant);
+      PresumedLoc Loc =
+          Context.getSourceManager().getPresumedLoc(Constant->getLocation());
+      AvailabilityInfo Availability = getAvailability(Constant);
+      DocComment Comment;
+      if (auto *RawComment = Context.getRawCommentForDeclNoCache(Constant))
+        Comment = RawComment->getFormattedLines(Context.getSourceManager(),
+                                                Context.getDiagnostics());
+
+      // Build declaration fragments and sub-heading for the enum constant.
+      DeclarationFragments Declaration =
+          DeclarationFragmentsBuilder::getFragmentsForEnumConstant(Constant);
+      DeclarationFragments SubHeading =
+          DeclarationFragmentsBuilder::getSubHeading(Constant);
+
+      API.addEnumConstant(EnumRecord, Name, USR, Loc, Availability, Comment,
+                          Declaration, SubHeading);
+    }
+  }
+
   ASTContext &Context;
   APISet API;
 };