[clang][extract-api] Add Objective-C protocol support

[zixuw]

Summary

Add support for Objective-C protocol declarations in ExtractAPI.

Depends on D122446

[dang]

clang/lib/ExtractAPI/ExtractAPIConsumer.cpp

269

I think we should be recording this in StringAllocator

clang/test/ExtractAPI/objc_interface.m

17 ↗

(On Diff #418343)

Should this be done in the interfaces patch?

[zixuw]

Rebase upstream changes in D122446:

• Move the change of the objc_interface.m test to D122446.

clang/lib/ExtractAPI/ExtractAPIConsumer.cpp

269

Same reply and concern in D122446

clang/include/clang/ExtractAPI/API.h

enum RecordKind {
     RK_EnumConstant,
     RK_Enum,
     RK_StructField,
     RK_Struct,
     RK_ObjCProperty,
     RK_ObjCIvar,
     RK_ObjCMethod,
     RK_ObjCInterface,
+    RK_ObjCProtocol,
   };
 
 private:
   const RecordKind Kind;
 
 public:
   RecordKind getKind() const { return Kind; }
 
struct ObjCInterfaceRecord : ObjCContainerRecord {
   static bool classof(const APIRecord *Record) {
     return Record->getKind() == RK_ObjCInterface;
   }
 
 private:
   virtual void anchor();
 };
 
+/// This holds information associated with Objective-C protocols.
+struct ObjCProtocolRecord : ObjCContainerRecord {
+  ObjCProtocolRecord(StringRef Name, StringRef USR, PresumedLoc Loc,
+                     const AvailabilityInfo &Availability,
+                     const DocComment &Comment,
+                     DeclarationFragments Declaration,
+                     DeclarationFragments SubHeading)
+      : ObjCContainerRecord(RK_ObjCProtocol, Name, USR, Loc, Availability,
+                            LinkageInfo::none(), Comment, Declaration,
+                            SubHeading) {}
+
+  static bool classof(const APIRecord *Record) {
+    return Record->getKind() == RK_ObjCProtocol;
+  }
+
+private:
+  virtual void anchor();
+};
+
 /// APISet holds the set of API records collected from given inputs.
 class APISet {
 public:
   /// 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
public:
   /// to generate the USR for \c D and keep it alive in APISet.
   ObjCInstanceVariableRecord *addObjCInstanceVariable(
       ObjCContainerRecord *Container, StringRef Name, StringRef USR,
       PresumedLoc Loc, const AvailabilityInfo &Availability,
       const DocComment &Comment, DeclarationFragments Declaration,
       DeclarationFragments SubHeading,
       ObjCInstanceVariableRecord::AccessControl Access);
 
+  /// Create and add an Objective-C protocol 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.
+  ObjCProtocolRecord *addObjCProtocol(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, std::unique_ptr<GlobalRecord>>;
 
   /// A map to store the set of EnumRecord%s with the declaration name as the
   /// key.
   using EnumRecordMap = llvm::MapVector<StringRef, std::unique_ptr<EnumRecord>>;
 
   /// A map to store the set of StructRecord%s with the declaration name as the
   /// key.
   using StructRecordMap =
       llvm::MapVector<StringRef, std::unique_ptr<StructRecord>>;
 
   /// A map to store the set of ObjCInterfaceRecord%s with the declaration name
   /// as the key.
   using ObjCInterfaceRecordMap =
       llvm::MapVector<StringRef, std::unique_ptr<ObjCInterfaceRecord>>;
 
+  /// A map to store the set of ObjCProtocolRecord%s with the declaration name
+  /// as the key.
+  using ObjCProtocolRecordMap =
+      llvm::MapVector<StringRef, std::unique_ptr<ObjCProtocolRecord>>;
+
   /// Get the target triple for the ExtractAPI invocation.
   const llvm::Triple &getTarget() const { return Target; }
 
   /// Get the language used by the APIs.
   Language getLanguage() const { return Lang; }
 
   const GlobalRecordMap &getGlobals() const { return Globals; }
   const EnumRecordMap &getEnums() const { return Enums; }
   const StructRecordMap &getStructs() const { return Structs; }
   const ObjCInterfaceRecordMap &getObjCInterfaces() const {
     return ObjCInterfaces;
   }
+  const ObjCProtocolRecordMap &getObjCProtocols() const {
+    return ObjCProtocols;
+  }
 
   /// 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);
 
private:
 
   const llvm::Triple Target;
   const Language Lang;
 
   GlobalRecordMap Globals;
   EnumRecordMap Enums;
   StructRecordMap Structs;
   ObjCInterfaceRecordMap ObjCInterfaces;
+  ObjCProtocolRecordMap ObjCProtocols;
 };
 
 } // namespace extractapi
 } // namespace clang
 
 #endif // LLVM_CLANG_EXTRACTAPI_API_H

clang/include/clang/ExtractAPI/DeclarationFragments.h

public:
   /// ObjCMethodDecl.
   static DeclarationFragments getFragmentsForObjCMethod(const ObjCMethodDecl *);
 
   /// Build DeclarationFragments for an Objective-C property declaration
   /// ObjCPropertyDecl.
   static DeclarationFragments
   getFragmentsForObjCProperty(const ObjCPropertyDecl *);
 
+  /// Build DeclarationFragments for an Objective-C protocol declaration
+  /// ObjCProtocolDecl.
+  static DeclarationFragments
+  getFragmentsForObjCProtocol(const ObjCProtocolDecl *);
+
   /// Build sub-heading fragments for a NamedDecl.
   static DeclarationFragments getSubHeading(const NamedDecl *);
 
   /// Build sub-heading fragments for an Objective-C method.
   static DeclarationFragments getSubHeading(const ObjCMethodDecl *);
 
   /// Build FunctionSignature for a function-like declaration \c FunctionT like
   /// FunctionDecl or ObjCMethodDecl.

clang/lib/ExtractAPI/API.cpp

ObjCInstanceVariableRecord *APISet::addObjCInstanceVariable(
     const DocComment &Comment, DeclarationFragments Declaration,
     DeclarationFragments SubHeading,
     ObjCInstanceVariableRecord::AccessControl Access) {
   auto Record = std::make_unique<ObjCInstanceVariableRecord>(
       Name, USR, Loc, Availability, Comment, Declaration, SubHeading, Access);
   return Container->Ivars.emplace_back(std::move(Record)).get();
 }
 
+ObjCProtocolRecord *APISet::addObjCProtocol(
+    StringRef Name, StringRef USR, PresumedLoc Loc,
+    const AvailabilityInfo &Availability, const DocComment &Comment,
+    DeclarationFragments Declaration, DeclarationFragments SubHeading) {
+  auto Result = ObjCProtocols.insert({Name, nullptr});
+  if (Result.second) {
+    // Create the record if it does not already exist.
+    auto Record = std::make_unique<ObjCProtocolRecord>(
+        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);
   return copyString(USR);
 }
 
 StringRef APISet::copyString(StringRef String) {
   if (String.empty())

 void EnumConstantRecord::anchor() {}
 void EnumRecord::anchor() {}
 void StructFieldRecord::anchor() {}
 void StructRecord::anchor() {}
 void ObjCPropertyRecord::anchor() {}
 void ObjCInstanceVariableRecord::anchor() {}
 void ObjCMethodRecord::anchor() {}
 void ObjCInterfaceRecord::anchor() {}
+void ObjCProtocolRecord::anchor() {}

clang/lib/ExtractAPI/DeclarationFragments.cpp

DeclarationFragments DeclarationFragmentsBuilder::getFragmentsForObjCProperty(
   return Fragments.appendSpace()
       .append(getFragmentsForType(Property->getType(),
                                   Property->getASTContext(), After))
       .append(Property->getName(),
               DeclarationFragments::FragmentKind::Identifier)
       .append(std::move(After));
 }
 
+DeclarationFragments DeclarationFragmentsBuilder::getFragmentsForObjCProtocol(
+    const ObjCProtocolDecl *Protocol) {
+  DeclarationFragments Fragments;
+  // Build basic protocol declaration.
+  Fragments.append("@protocol", DeclarationFragments::FragmentKind::Keyword)
+      .appendSpace()
+      .append(Protocol->getName(),
+              DeclarationFragments::FragmentKind::Identifier);
+
+  // If this protocol conforms to other protocols, build the conformance list.
+  if (!Protocol->protocols().empty()) {
+    Fragments.append(" <", DeclarationFragments::FragmentKind::Text);
+    for (ObjCProtocolDecl::protocol_iterator It = Protocol->protocol_begin();
+         It != Protocol->protocol_end(); It++) {
+      // Add a leading comma if this is not the first protocol rendered.
+      if (It != Protocol->protocol_begin())
+        Fragments.append(", ", DeclarationFragments::FragmentKind::Text);
+
+      SmallString<128> USR;
+      index::generateUSRForDecl(*It, USR);
+      Fragments.append((*It)->getName(),
+                       DeclarationFragments::FragmentKind::TypeIdentifier, USR);
+    }
+    Fragments.append(">", DeclarationFragments::FragmentKind::Text);
+  }
+
+  return Fragments;
+}
+
 template <typename FunctionT>
 FunctionSignature
 DeclarationFragmentsBuilder::getFunctionSignature(const FunctionT *Function) {
   FunctionSignature Signature;
 
   DeclarationFragments ReturnType, After;
   ReturnType
       .append(getFragmentsForType(Function->getReturnType(),

clang/lib/ExtractAPI/ExtractAPIConsumer.cpp

bool VisitObjCInterfaceDecl(const ObjCInterfaceDecl *Decl) {
     recordObjCMethods(ObjCInterfaceRecord, Decl->methods());
     recordObjCProperties(ObjCInterfaceRecord, Decl->properties());
     recordObjCInstanceVariables(ObjCInterfaceRecord, Decl->ivars());
     recordObjCProtocols(ObjCInterfaceRecord, Decl->protocols());
 
     return true;
   }
 
+  bool VisitObjCProtocolDecl(const ObjCProtocolDecl *Decl) {
+    // Skip forward declaration for protocols (@protocol).
+    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 protocol.
+    DeclarationFragments Declaration =
+        DeclarationFragmentsBuilder::getFragmentsForObjCProtocol(Decl);
+    DeclarationFragments SubHeading =
+        DeclarationFragmentsBuilder::getSubHeading(Decl);
+
+    ObjCProtocolRecord *ObjCProtocolRecord = API.addObjCProtocol(
+        Name, USR, Loc, Availability, Comment, Declaration, SubHeading);
+
+    recordObjCMethods(ObjCProtocolRecord, Decl->methods());
+    recordObjCProperties(ObjCProtocolRecord, Decl->properties());
+    recordObjCProtocols(ObjCProtocolRecord, Decl->protocols());
+
+    return true;
+  }
+
 private:
   /// Get availability information of the declaration \p D.
   AvailabilityInfo getAvailability(const Decl *D) const {
     StringRef PlatformName = Context.getTargetInfo().getPlatformName();
 
     AvailabilityInfo Availability;
     // Collect availability attributes from all redeclarations.
     for (const auto *RD : D->redecls()) {

clang/lib/ExtractAPI/Serialization/SymbolGraphSerializer.cpp

Object serializeSymbolKind(const APIRecord &Record, Language Lang) {
   case APIRecord::RK_ObjCProperty:
     Kind["identifier"] = AddLangPrefix("property");
     Kind["displayName"] = "Instance Property";
     break;
   case APIRecord::RK_ObjCInterface:
     Kind["identifier"] = AddLangPrefix("class");
     Kind["displayName"] = "Class";
     break;
+  case APIRecord::RK_ObjCProtocol:
+    Kind["identifier"] = AddLangPrefix("protocol");
+    Kind["displayName"] = "Protocol";
+    break;
   }
 
   return Kind;
 }
 
 } // namespace
 
 void SymbolGraphSerializer::anchor() {}
Object SymbolGraphSerializer::serialize() {
   // Serialize struct records in the API set.
   for (const auto &Struct : API.getStructs())
     serializeStructRecord(*Struct.second);
 
   // Serialize Objective-C interface records in the API set.
   for (const auto &ObjCInterface : API.getObjCInterfaces())
     serializeObjCContainerRecord(*ObjCInterface.second);
 
+  // Serialize Objective-C protocol records in the API set.
+  for (const auto &ObjCProtocol : API.getObjCProtocols())
+    serializeObjCContainerRecord(*ObjCProtocol.second);
+
   Root["symbols"] = std::move(Symbols);
   Root["relationhips"] = std::move(Relationships);
 
   return Root;
 }
 
 void SymbolGraphSerializer::serialize(raw_ostream &os) {
   Object root = serialize();
   if (Options.Compact)
     os << formatv("{0}", Value(std::move(root))) << "\n";
   else
     os << formatv("{0:2}", Value(std::move(root))) << "\n";
 }

clang/test/ExtractAPI/objc_protocol.m

+// RUN: rm -rf %t
+// RUN: split-file %s %t
+// RUN: sed -e "s@INPUT_DIR@%/t@g" %t/reference.output.json.in >> \
+// RUN: %t/reference.output.json
+// RUN: %clang -extract-api -x objective-c-header -target arm64-apple-macosx \
+// RUN: %t/input.h -o %t/output.json | FileCheck -allow-empty %s
+
+// Generator version is not consistent across test runs, normalize it.
+// RUN: sed -e "s@\"generator\": \".*\"@\"generator\": \"?\"@g" \
+// RUN: %t/output.json >> %t/output-normalized.json
+// RUN: diff %t/reference.output.json %t/output-normalized.json
+
+// CHECK-NOT: error:
+// CHECK-NOT: warning:
+
+//--- input.h
+@protocol Protocol
+@end
+
+@protocol AnotherProtocol <Protocol>
+@end
+
+//--- reference.output.json.in
+{
+  "metadata": {
+    "formatVersion": {
+      "major": 0,
+      "minor": 5,
+      "patch": 3
+    },
+    "generator": "?"
+  },
+  "module": {
+    "name": "",
+    "platform": {
+      "architecture": "arm64",
+      "operatingSystem": {
+        "minimumVersion": {
+          "major": 11,
+          "minor": 0,
+          "patch": 0
+        },
+        "name": "macosx"
+      },
+      "vendor": "apple"
+    }
+  },
+  "relationhips": [
+    {
+      "kind": "conformsTo",
+      "source": "c:objc(pl)AnotherProtocol",
+      "target": "c:objc(pl)Protocol"
+    }
+  ],
+  "symbols": [
+    {
+      "declarationFragments": [
+        {
+          "kind": "keyword",
+          "spelling": "@protocol"
+        },
+        {
+          "kind": "text",
+          "spelling": " "
+        },
+        {
+          "kind": "identifier",
+          "spelling": "Protocol"
+        }
+      ],
+      "identifier": {
+        "interfaceLanguage": "objective-c",
+        "precise": "c:objc(pl)Protocol"
+      },
+      "kind": {
+        "displayName": "Protocol",
+        "identifier": "objective-c.protocol"
+      },
+      "location": {
+        "character": 11,
+        "line": 1,
+        "uri": "file://INPUT_DIR/input.h"
+      },
+      "names": {
+        "subHeading": [
+          {
+            "kind": "identifier",
+            "spelling": "Protocol"
+          }
+        ],
+        "title": "Protocol"
+      }
+    },
+    {
+      "declarationFragments": [
+        {
+          "kind": "keyword",
+          "spelling": "@protocol"
+        },
+        {
+          "kind": "text",
+          "spelling": " "
+        },
+        {
+          "kind": "identifier",
+          "spelling": "AnotherProtocol"
+        },
+        {
+          "kind": "text",
+          "spelling": " <"
+        },
+        {
+          "kind": "typeIdentifier",
+          "preciseIdentifier": "c:objc(pl)Protocol",
+          "spelling": "Protocol"
+        },
+        {
+          "kind": "text",
+          "spelling": ">"
+        }
+      ],
+      "identifier": {
+        "interfaceLanguage": "objective-c",
+        "precise": "c:objc(pl)AnotherProtocol"
+      },
+      "kind": {
+        "displayName": "Protocol",
+        "identifier": "objective-c.protocol"
+      },
+      "location": {
+        "character": 11,
+        "line": 4,
+        "uri": "file://INPUT_DIR/input.h"
+      },
+      "names": {
+        "subHeading": [
+          {
+            "kind": "identifier",
+            "spelling": "AnotherProtocol"
+          }
+        ],
+        "title": "AnotherProtocol"
+      }
+    }
+  ]
+}