[clang][ExtractAPI] Allow users to specify a list of symbols to ignore

Adds a `--extract-api-ignores=` command line option that allows users to
provide a file containing a new line separated list of symbols to
unconditionally ignore when extracting API information.

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

Author: daniel-grumberg

clang/include/clang/Basic/DiagnosticFrontendKinds.td

@@ -331,4 +331,7 @@ def warn_profile_data_misexpect : Warning<
   InGroup<MisExpect>;
 } // end of instrumentation issue category
 
+def err_extract_api_ignores_file_not_found :
+  Error<"file '%0' specified by '--extract-api-ignores=' not found">, DefaultFatal;
+
 }

clang/include/clang/Driver/Options.td

@@ -1121,6 +1121,9 @@ def extract_api : Flag<["-"], "extract-api">, Flags<[CC1Option]>, Group<Action_G
   HelpText<"Extract API information">;
 def product_name_EQ: Joined<["--"], "product-name=">, Flags<[CC1Option]>,
   MarshallingInfoString<FrontendOpts<"ProductName">>;
+def extract_api_ignores_EQ: Joined<["--"], "extract-api-ignores=">, Flags<[CC1Option]>,
+    HelpText<"File containing a new line separated list of API symbols to ignore when extracting API information.">,
+    MarshallingInfoString<FrontendOpts<"ExtractAPIIgnoresFile">>;
 def e : JoinedOrSeparate<["-"], "e">, Flags<[LinkerInput]>, Group<Link_Group>;
 def fmax_tokens_EQ : Joined<["-"], "fmax-tokens=">, Group<f_Group>, Flags<[CC1Option]>,
   HelpText<"Max total number of preprocessed tokens for -Wmax-tokens.">,

clang/include/clang/ExtractAPI/APIIgnoresList.h

@@ -0,0 +1,74 @@
+//===- ExtractAPI/APIIgnoresList.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.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+///
+/// \file This file defines APIIgnoresList which is a type that allows querying
+/// a file containing symbols to ignore when extracting API information.
+///
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_CLANG_API_IGNORES_LIST_H
+#define LLVM_CLANG_API_IGNORES_LIST_H
+
+#include "clang/Basic/FileManager.h"
+#include "llvm/ADT/SmallVector.h"
+#include "llvm/ADT/StringRef.h"
+#include "llvm/Support/Error.h"
+#include "llvm/Support/raw_ostream.h"
+
+#include <memory>
+#include <system_error>
+
+namespace llvm {
+class MemoryBuffer;
+} // namespace llvm
+
+namespace clang {
+namespace extractapi {
+
+struct IgnoresFileNotFound : public llvm::ErrorInfo<IgnoresFileNotFound> {
+  std::string Path;
+  static char ID;
+
+  explicit IgnoresFileNotFound(StringRef Path) : Path(Path) {}
+
+  virtual void log(llvm::raw_ostream &os) const override;
+
+  virtual std::error_code convertToErrorCode() const override;
+};
+
+/// A type that provides access to a new line separated list of symbol names to
+/// ignore when extracting API information.
+struct APIIgnoresList {
+  /// The API to use for generating from the file at \p IgnoresFilePath.
+  ///
+  /// \returns an initialized APIIgnoresList or an Error.
+  static llvm::Expected<APIIgnoresList> create(llvm::StringRef IgnoresFilePath,
+                                               FileManager &FM);
+
+  APIIgnoresList() = default;
+
+  /// Check if \p SymbolName is specified in the APIIgnoresList and if it should
+  /// therefore be ignored.
+  bool shouldIgnore(llvm::StringRef SymbolName) const;
+
+private:
+  using SymbolNameList = llvm::SmallVector<llvm::StringRef, 32>;
+
+  APIIgnoresList(SymbolNameList SymbolsToIgnore,
+                 std::unique_ptr<llvm::MemoryBuffer> Buffer)
+      : SymbolsToIgnore(std::move(SymbolsToIgnore)), Buffer(std::move(Buffer)) {
+  }
+
+  SymbolNameList SymbolsToIgnore;
+  std::unique_ptr<llvm::MemoryBuffer> Buffer;
+};
+
+} // namespace extractapi
+} // namespace clang
+
+#endif // LLVM_CLANG_API_IGNORES_LIST_H

clang/include/clang/ExtractAPI/FrontendActions.h

@@ -15,6 +15,7 @@
 #define LLVM_CLANG_EXTRACTAPI_FRONTEND_ACTIONS_H
 
 #include "clang/ExtractAPI/API.h"
+#include "clang/ExtractAPI/APIIgnoresList.h"
 #include "clang/Frontend/FrontendAction.h"
 
 namespace clang {
@@ -39,6 +40,9 @@ class ExtractAPIAction : public ASTFrontendAction {
   /// files.
   std::unique_ptr<llvm::MemoryBuffer> Buffer;
 
+  /// The list of symbols to ignore during serialization
+  extractapi::APIIgnoresList IgnoresList;
+
   /// The input file originally provided on the command line.
   ///
   /// This captures the spelling used to include the file and whether the

clang/include/clang/ExtractAPI/Serialization/SerializerBase.h

@@ -15,6 +15,7 @@
 #define LLVM_CLANG_EXTRACTAPI_SERIALIZATION_SERIALIZERBASE_H
 
 #include "clang/ExtractAPI/API.h"
+#include "clang/ExtractAPI/APIIgnoresList.h"
 #include "llvm/Support/raw_ostream.h"
 
 namespace clang {
@@ -40,6 +41,11 @@ class APISerializer {
   /// Note: This should be used for populating metadata about the API.
   StringRef ProductName;
 
+  /// The list of symbols to ignore.
+  ///
+  /// Note: This should be consulted before emitting a symbol.
+  const APIIgnoresList &IgnoresList;
+
   APISerializerOption Options;
 
 public:
@@ -51,8 +57,10 @@ class APISerializer {
 
 protected:
   APISerializer(const APISet &API, StringRef ProductName,
+                const APIIgnoresList &IgnoresList,
                 APISerializerOption Options = {})
-      : API(API), ProductName(ProductName), Options(Options) {}
+      : API(API), ProductName(ProductName), IgnoresList(IgnoresList),
+        Options(Options) {}
 
   virtual ~APISerializer() = default;
 };

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

@@ -18,6 +18,7 @@
 #define LLVM_CLANG_EXTRACTAPI_SERIALIZATION_SYMBOLGRAPHSERIALIZER_H
 
 #include "clang/ExtractAPI/API.h"
+#include "clang/ExtractAPI/APIIgnoresList.h"
 #include "clang/ExtractAPI/Serialization/SerializerBase.h"
 #include "llvm/ADT/SmallVector.h"
 #include "llvm/Support/JSON.h"
@@ -168,8 +169,9 @@ class SymbolGraphSerializer : public APISerializer {
 
 public:
   SymbolGraphSerializer(const APISet &API, StringRef ProductName,
+                        const APIIgnoresList &IgnoresList,
                         APISerializerOption Options = {})
-      : APISerializer(API, ProductName, Options) {}
+      : APISerializer(API, ProductName, IgnoresList, Options) {}
 };
 
 } // namespace extractapi

clang/include/clang/Frontend/FrontendOptions.h

@@ -454,6 +454,10 @@ class FrontendOptions {
   /// The name of the product the input files belong too.
   std::string ProductName;
 
+  // Currently this is only used as part of the `-extract-api` action.
+  /// The file providing a list of APIs to ignore when extracting documentation
+  std::string ExtractAPIIgnoresFile;
+
   /// Args to pass to the plugins
   std::map<std::string, std::vector<std::string>> PluginArgs;
 

clang/lib/Driver/ToolChains/Clang.cpp

@@ -4813,6 +4813,9 @@ void Clang::ConstructJob(Compilation &C, const JobAction &JA,
     CmdArgs.push_back("-extract-api");
     if (Arg *ProductNameArg = Args.getLastArg(options::OPT_product_name_EQ))
       ProductNameArg->render(Args, CmdArgs);
+    if (Arg *ExtractAPIIgnoresFileArg =
+            Args.getLastArg(options::OPT_extract_api_ignores_EQ))
+      ExtractAPIIgnoresFileArg->render(Args, CmdArgs);
   } else {
     assert((isa<CompileJobAction>(JA) || isa<BackendJobAction>(JA)) &&
            "Invalid action for clang tool.");

clang/lib/ExtractAPI/APIIgnoresList.cpp

@@ -0,0 +1,53 @@
+//===- ExtractAPI/APIIgnoresList.cpp -------*- C++ -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+///
+/// \file
+/// This file implements APIIgnoresList that allows users to specifiy a file
+/// containing symbols to ignore during API extraction.
+///
+//===----------------------------------------------------------------------===//
+
+#include "clang/ExtractAPI/APIIgnoresList.h"
+#include "clang/Basic/FileManager.h"
+#include "llvm/ADT/STLExtras.h"
+#include "llvm/Support/Error.h"
+
+using namespace clang;
+using namespace clang::extractapi;
+using namespace llvm;
+
+char IgnoresFileNotFound::ID;
+
+void IgnoresFileNotFound::log(llvm::raw_ostream &os) const {
+  os << "Could not find API ignores file " << Path;
+}
+
+std::error_code IgnoresFileNotFound::convertToErrorCode() const {
+  return llvm::inconvertibleErrorCode();
+}
+
+Expected<APIIgnoresList> APIIgnoresList::create(StringRef IgnoresFilePath,
+                                                FileManager &FM) {
+  auto BufferOrErr = FM.getBufferForFile(IgnoresFilePath);
+  if (!BufferOrErr)
+    return make_error<IgnoresFileNotFound>(IgnoresFilePath);
+
+  auto Buffer = std::move(BufferOrErr.get());
+  SmallVector<StringRef, 32> Lines;
+  Buffer->getBuffer().split(Lines, '\n', /*MaxSplit*/ -1, /*KeepEmpty*/ false);
+  // Symbol names don't have spaces in them, let's just remove these in case the
+  // input is slighlty malformed.
+  transform(Lines, Lines.begin(), [](StringRef Line) { return Line.trim(); });
+  sort(Lines);
+  return APIIgnoresList(std::move(Lines), std::move(Buffer));
+}
+
+bool APIIgnoresList::shouldIgnore(StringRef SymbolName) const {
+  auto It = lower_bound(SymbolsToIgnore, SymbolName);
+  return (It != SymbolsToIgnore.end()) && (*It == SymbolName);
+}

clang/lib/ExtractAPI/CMakeLists.txt

@@ -4,6 +4,7 @@ set(LLVM_LINK_COMPONENTS
 
 add_clang_library(clangExtractAPI
   API.cpp
+  APIIgnoresList.cpp
   AvailabilityInfo.cpp
   ExtractAPIConsumer.cpp
   DeclarationFragments.cpp