[clang-tools-extra] [clang-doc] Add --asset option to clang-doc (PR #94717)

via cfe-commits cfe-commits at lists.llvm.org
Thu Jun 6 22:44:22 PDT 2024


github-actions[bot] wrote:

<!--LLVM CODE FORMAT COMMENT: {clang-format}-->


:warning: C/C++ code formatter, clang-format found issues in your code. :warning:

<details>
<summary>
You can test this locally with the following command:
</summary>

``````````bash
git-clang-format --diff 98714866830f505d7bb87de6b92a28f280a34b9b d535cb7b7c92a22931b276a8c9fe97a2f04c2258 -- clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
``````````

</details>

<details>
<summary>
View the diff from clang-format here.
</summary>

``````````diff
diff --git a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
index ab6f6198aa..b72767d201 100644
--- a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
+++ b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
@@ -54,38 +54,38 @@ static llvm::cl::extrahelp CommonHelp(CommonOptionsParser::HelpMessage);
 static llvm::cl::OptionCategory ClangDocCategory("clang-doc options");
 
 static llvm::cl::opt<std::string>
-        ProjectName("project-name", llvm::cl::desc("Name of project."),
-                    llvm::cl::cat(ClangDocCategory));
+    ProjectName("project-name", llvm::cl::desc("Name of project."),
+                llvm::cl::cat(ClangDocCategory));
 
 static llvm::cl::opt<bool> IgnoreMappingFailures(
-        "ignore-map-errors",
-        llvm::cl::desc("Continue if files are not mapped correctly."),
-        llvm::cl::init(true), llvm::cl::cat(ClangDocCategory));
+    "ignore-map-errors",
+    llvm::cl::desc("Continue if files are not mapped correctly."),
+    llvm::cl::init(true), llvm::cl::cat(ClangDocCategory));
 
 static llvm::cl::opt<std::string>
-        OutDirectory("output",
-                     llvm::cl::desc("Directory for outputting generated files."),
-                     llvm::cl::init("docs"), llvm::cl::cat(ClangDocCategory));
+    OutDirectory("output",
+                 llvm::cl::desc("Directory for outputting generated files."),
+                 llvm::cl::init("docs"), llvm::cl::cat(ClangDocCategory));
 
 static llvm::cl::opt<bool>
-        PublicOnly("public", llvm::cl::desc("Document only public declarations."),
-                   llvm::cl::init(false), llvm::cl::cat(ClangDocCategory));
+    PublicOnly("public", llvm::cl::desc("Document only public declarations."),
+               llvm::cl::init(false), llvm::cl::cat(ClangDocCategory));
 
 static llvm::cl::opt<bool> DoxygenOnly(
-        "doxygen",
-        llvm::cl::desc("Use only doxygen-style comments to generate docs."),
-        llvm::cl::init(false), llvm::cl::cat(ClangDocCategory));
+    "doxygen",
+    llvm::cl::desc("Use only doxygen-style comments to generate docs."),
+    llvm::cl::init(false), llvm::cl::cat(ClangDocCategory));
 
 static llvm::cl::list<std::string> UserStylesheets(
-        "stylesheets", llvm::cl::CommaSeparated,
-        llvm::cl::desc("CSS stylesheets to extend the default styles."),
-        llvm::cl::cat(ClangDocCategory));
+    "stylesheets", llvm::cl::CommaSeparated,
+    llvm::cl::desc("CSS stylesheets to extend the default styles."),
+    llvm::cl::cat(ClangDocCategory));
 
 static llvm::cl::opt<std::string>
-        UserAssetPath("asset",
-                      llvm::cl::desc("User supplied asset path for html output to "
-                                     "override the default css and js files"),
-                      llvm::cl::cat(ClangDocCategory));
+    UserAssetPath("asset",
+                  llvm::cl::desc("User supplied asset path for html output to "
+                                 "override the default css and js files"),
+                  llvm::cl::cat(ClangDocCategory));
 
 static llvm::cl::opt<std::string> SourceRoot("source-root", llvm::cl::desc(R"(
 Directory where processed files are stored.
@@ -94,38 +94,38 @@ generated if the file is in this dir.)"),
                                              llvm::cl::cat(ClangDocCategory));
 
 static llvm::cl::opt<std::string>
-        RepositoryUrl("repository", llvm::cl::desc(R"(
+    RepositoryUrl("repository", llvm::cl::desc(R"(
 URL of repository that hosts code.
 Used for links to definition locations.)"),
-                      llvm::cl::cat(ClangDocCategory));
+                  llvm::cl::cat(ClangDocCategory));
 
 enum OutputFormatTy {
-    md,
-    yaml,
-    html,
+  md,
+  yaml,
+  html,
 };
 
 static llvm::cl::opt<OutputFormatTy>
-        FormatEnum("format", llvm::cl::desc("Format for outputted docs."),
-                   llvm::cl::values(clEnumValN(OutputFormatTy::yaml, "yaml",
-                                               "Documentation in YAML format."),
-                                    clEnumValN(OutputFormatTy::md, "md",
-                                               "Documentation in MD format."),
-                                    clEnumValN(OutputFormatTy::html, "html",
-                                               "Documentation in HTML format.")),
-                   llvm::cl::init(OutputFormatTy::yaml),
-                   llvm::cl::cat(ClangDocCategory));
+    FormatEnum("format", llvm::cl::desc("Format for outputted docs."),
+               llvm::cl::values(clEnumValN(OutputFormatTy::yaml, "yaml",
+                                           "Documentation in YAML format."),
+                                clEnumValN(OutputFormatTy::md, "md",
+                                           "Documentation in MD format."),
+                                clEnumValN(OutputFormatTy::html, "html",
+                                           "Documentation in HTML format.")),
+               llvm::cl::init(OutputFormatTy::yaml),
+               llvm::cl::cat(ClangDocCategory));
 
 std::string getFormatString() {
-    switch (FormatEnum) {
-        case OutputFormatTy::yaml:
-            return "yaml";
-        case OutputFormatTy::md:
-            return "md";
-        case OutputFormatTy::html:
-            return "html";
-    }
-    llvm_unreachable("Unknown OutputFormatTy");
+  switch (FormatEnum) {
+  case OutputFormatTy::yaml:
+    return "yaml";
+  case OutputFormatTy::md:
+    return "md";
+  case OutputFormatTy::html:
+    return "html";
+  }
+  llvm_unreachable("Unknown OutputFormatTy");
 }
 
 // This function isn't referenced outside its translation unit, but it
@@ -134,58 +134,58 @@ std::string getFormatString() {
 // address of main, and some platforms can't implement GetMainExecutable
 // without being given the address of a function in the main executable).
 std::string GetExecutablePath(const char *Argv0, void *MainAddr) {
-    return llvm::sys::fs::getMainExecutable(Argv0, MainAddr);
+  return llvm::sys::fs::getMainExecutable(Argv0, MainAddr);
 }
 
 void GetAssetFiles(clang::doc::ClangDocContext &CDCtx) {
-    std::error_code Code;
-    for (auto DirIt = llvm::sys::fs::directory_iterator(
-            std::string(UserAssetPath), Code),
-                 dir_end = llvm::sys::fs::directory_iterator();
-         !Code && DirIt != dir_end; DirIt.increment(Code)) {
-        llvm::SmallString<128> filePath = llvm::SmallString<128>(DirIt->path());
-        if (llvm::sys::fs::is_regular_file(filePath)) {
-            if (filePath.ends_with(".css")) {
-                CDCtx.UserStylesheets.insert(CDCtx.UserStylesheets.begin(),
-                                             std::string(filePath));
-            } else if (filePath.ends_with(".js")) {
-                CDCtx.FilesToCopy.emplace_back(filePath.str());
-            }
-        }
+  std::error_code Code;
+  for (auto DirIt = llvm::sys::fs::directory_iterator(
+                std::string(UserAssetPath), Code),
+            dir_end = llvm::sys::fs::directory_iterator();
+       !Code && DirIt != dir_end; DirIt.increment(Code)) {
+    llvm::SmallString<128> filePath = llvm::SmallString<128>(DirIt->path());
+    if (llvm::sys::fs::is_regular_file(filePath)) {
+      if (filePath.ends_with(".css")) {
+        CDCtx.UserStylesheets.insert(CDCtx.UserStylesheets.begin(),
+                                     std::string(filePath));
+      } else if (filePath.ends_with(".js")) {
+        CDCtx.FilesToCopy.emplace_back(filePath.str());
+      }
     }
+  }
 }
 
 void GetDefaultAssetFiles(const char *Argv0,
                           clang::doc::ClangDocContext &CDCtx) {
-    void *MainAddr = (void *)(intptr_t)GetExecutablePath;
-    std::string ClangDocPath = GetExecutablePath(Argv0, MainAddr);
-    llvm::SmallString<128> NativeClangDocPath;
-    llvm::sys::path::native(ClangDocPath, NativeClangDocPath);
-
-    llvm::SmallString<128> AssetsPath;
-    AssetsPath = llvm::sys::path::parent_path(NativeClangDocPath);
-    llvm::sys::path::append(AssetsPath, "..", "share", "clang");
-    llvm::SmallString<128> DefaultStylesheet;
-    llvm::sys::path::native(AssetsPath, DefaultStylesheet);
-    llvm::sys::path::append(DefaultStylesheet,
-                            "clang-doc-default-stylesheet.css");
-    llvm::SmallString<128> IndexJS;
-    llvm::sys::path::native(AssetsPath, IndexJS);
-    llvm::sys::path::append(IndexJS, "index.js");
-    CDCtx.UserStylesheets.insert(CDCtx.UserStylesheets.begin(),
-                                 std::string(DefaultStylesheet));
-    CDCtx.FilesToCopy.emplace_back(IndexJS.str());
-
-    llvm::outs() << "No default asset path found using default asset path: "
-                 << AssetsPath << "\n";
+  void *MainAddr = (void *)(intptr_t)GetExecutablePath;
+  std::string ClangDocPath = GetExecutablePath(Argv0, MainAddr);
+  llvm::SmallString<128> NativeClangDocPath;
+  llvm::sys::path::native(ClangDocPath, NativeClangDocPath);
+
+  llvm::SmallString<128> AssetsPath;
+  AssetsPath = llvm::sys::path::parent_path(NativeClangDocPath);
+  llvm::sys::path::append(AssetsPath, "..", "share", "clang");
+  llvm::SmallString<128> DefaultStylesheet;
+  llvm::sys::path::native(AssetsPath, DefaultStylesheet);
+  llvm::sys::path::append(DefaultStylesheet,
+                          "clang-doc-default-stylesheet.css");
+  llvm::SmallString<128> IndexJS;
+  llvm::sys::path::native(AssetsPath, IndexJS);
+  llvm::sys::path::append(IndexJS, "index.js");
+  CDCtx.UserStylesheets.insert(CDCtx.UserStylesheets.begin(),
+                               std::string(DefaultStylesheet));
+  CDCtx.FilesToCopy.emplace_back(IndexJS.str());
+
+  llvm::outs() << "No default asset path found using default asset path: "
+               << AssetsPath << "\n";
 }
 
 int main(int argc, const char **argv) {
-    llvm::sys::PrintStackTraceOnErrorSignal(argv[0]);
-    std::error_code OK;
+  llvm::sys::PrintStackTraceOnErrorSignal(argv[0]);
+  std::error_code OK;
 
-    const char *Overview =
-            R"(Generates documentation from source code and comments.
+  const char *Overview =
+      R"(Generates documentation from source code and comments.
 
 Example usage for files without flags (default):
 
@@ -196,150 +196,150 @@ Example usage for a project using a compile commands database:
   $ clang-doc --executor=all-TUs compile_commands.json
 )";
 
-    auto Executor = clang::tooling::createExecutorFromCommandLineArgs(
-            argc, argv, ClangDocCategory, Overview);
-
-    if (!Executor) {
-        llvm::errs() << toString(Executor.takeError()) << "\n";
-        return 1;
-    }
-
-    // Fail early if an invalid format was provided.
-    std::string Format = getFormatString();
-    llvm::outs() << "Emiting docs in " << Format << " format.\n";
-    auto G = doc::findGeneratorByName(Format);
-    if (!G) {
-        llvm::errs() << toString(G.takeError()) << "\n";
-        return 1;
+  auto Executor = clang::tooling::createExecutorFromCommandLineArgs(
+      argc, argv, ClangDocCategory, Overview);
+
+  if (!Executor) {
+    llvm::errs() << toString(Executor.takeError()) << "\n";
+    return 1;
+  }
+
+  // Fail early if an invalid format was provided.
+  std::string Format = getFormatString();
+  llvm::outs() << "Emiting docs in " << Format << " format.\n";
+  auto G = doc::findGeneratorByName(Format);
+  if (!G) {
+    llvm::errs() << toString(G.takeError()) << "\n";
+    return 1;
+  }
+
+  ArgumentsAdjuster ArgAdjuster;
+  if (!DoxygenOnly)
+    ArgAdjuster = combineAdjusters(
+        getInsertArgumentAdjuster("-fparse-all-comments",
+                                  tooling::ArgumentInsertPosition::END),
+        ArgAdjuster);
+
+  clang::doc::ClangDocContext CDCtx = {
+      Executor->get()->getExecutionContext(),
+      ProjectName,
+      PublicOnly,
+      OutDirectory,
+      SourceRoot,
+      RepositoryUrl,
+      {UserStylesheets.begin(), UserStylesheets.end()},
+      {"index.js", "index_json.js"}};
+
+  if (Format == "html") {
+    if (!UserAssetPath.empty() &&
+        llvm::sys::fs::is_directory(std::string(UserAssetPath))) {
+      GetAssetFiles(CDCtx);
+    } else {
+      GetDefaultAssetFiles(argv[0], CDCtx);
     }
-
-    ArgumentsAdjuster ArgAdjuster;
-    if (!DoxygenOnly)
-        ArgAdjuster = combineAdjusters(
-                getInsertArgumentAdjuster("-fparse-all-comments",
-                                          tooling::ArgumentInsertPosition::END),
-                ArgAdjuster);
-
-    clang::doc::ClangDocContext CDCtx = {
-            Executor->get()->getExecutionContext(),
-            ProjectName,
-            PublicOnly,
-            OutDirectory,
-            SourceRoot,
-            RepositoryUrl,
-            {UserStylesheets.begin(), UserStylesheets.end()},
-            {"index.js", "index_json.js"}};
-
-    if (Format == "html") {
-        if (!UserAssetPath.empty() &&
-            llvm::sys::fs::is_directory(std::string(UserAssetPath))) {
-            GetAssetFiles(CDCtx);
-        } else {
-            GetDefaultAssetFiles(argv[0], CDCtx);
-        }
+  }
+
+  // Mapping phase
+  llvm::outs() << "Mapping decls...\n";
+  auto Err =
+      Executor->get()->execute(doc::newMapperActionFactory(CDCtx), ArgAdjuster);
+  if (Err) {
+    if (IgnoreMappingFailures)
+      llvm::errs() << "Error mapping decls in files. Clang-doc will ignore "
+                      "these files and continue:\n"
+                   << toString(std::move(Err)) << "\n";
+    else {
+      llvm::errs() << toString(std::move(Err)) << "\n";
+      return 1;
     }
-
-    // Mapping phase
-    llvm::outs() << "Mapping decls...\n";
-    auto Err =
-            Executor->get()->execute(doc::newMapperActionFactory(CDCtx), ArgAdjuster);
-    if (Err) {
-        if (IgnoreMappingFailures)
-            llvm::errs() << "Error mapping decls in files. Clang-doc will ignore "
-                            "these files and continue:\n"
-                         << toString(std::move(Err)) << "\n";
-        else {
-            llvm::errs() << toString(std::move(Err)) << "\n";
-            return 1;
+  }
+
+  // Collect values into output by key.
+  // In ToolResults, the Key is the hashed USR and the value is the
+  // bitcode-encoded representation of the Info object.
+  llvm::outs() << "Collecting infos...\n";
+  llvm::StringMap<std::vector<StringRef>> USRToBitcode;
+  Executor->get()->getToolResults()->forEachResult(
+      [&](StringRef Key, StringRef Value) {
+        auto R = USRToBitcode.try_emplace(Key, std::vector<StringRef>());
+        R.first->second.emplace_back(Value);
+      });
+
+  // Collects all Infos according to their unique USR value. This map is added
+  // to from the thread pool below and is protected by the USRToInfoMutex.
+  llvm::sys::Mutex USRToInfoMutex;
+  llvm::StringMap<std::unique_ptr<doc::Info>> USRToInfo;
+
+  // First reducing phase (reduce all decls into one info per decl).
+  llvm::outs() << "Reducing " << USRToBitcode.size() << " infos...\n";
+  std::atomic<bool> Error;
+  Error = false;
+  llvm::sys::Mutex IndexMutex;
+  // ExecutorConcurrency is a flag exposed by AllTUsExecution.h
+  llvm::DefaultThreadPool Pool(llvm::hardware_concurrency(ExecutorConcurrency));
+  for (auto &Group : USRToBitcode) {
+    Pool.async([&]() {
+      std::vector<std::unique_ptr<doc::Info>> Infos;
+
+      for (auto &Bitcode : Group.getValue()) {
+        llvm::BitstreamCursor Stream(Bitcode);
+        doc::ClangDocBitcodeReader Reader(Stream);
+        auto ReadInfos = Reader.readBitcode();
+        if (!ReadInfos) {
+          llvm::errs() << toString(ReadInfos.takeError()) << "\n";
+          Error = true;
+          return;
         }
-    }
-
-    // Collect values into output by key.
-    // In ToolResults, the Key is the hashed USR and the value is the
-    // bitcode-encoded representation of the Info object.
-    llvm::outs() << "Collecting infos...\n";
-    llvm::StringMap<std::vector<StringRef>> USRToBitcode;
-    Executor->get()->getToolResults()->forEachResult(
-            [&](StringRef Key, StringRef Value) {
-                auto R = USRToBitcode.try_emplace(Key, std::vector<StringRef>());
-                R.first->second.emplace_back(Value);
-            });
-
-    // Collects all Infos according to their unique USR value. This map is added
-    // to from the thread pool below and is protected by the USRToInfoMutex.
-    llvm::sys::Mutex USRToInfoMutex;
-    llvm::StringMap<std::unique_ptr<doc::Info>> USRToInfo;
-
-    // First reducing phase (reduce all decls into one info per decl).
-    llvm::outs() << "Reducing " << USRToBitcode.size() << " infos...\n";
-    std::atomic<bool> Error;
-    Error = false;
-    llvm::sys::Mutex IndexMutex;
-    // ExecutorConcurrency is a flag exposed by AllTUsExecution.h
-    llvm::DefaultThreadPool Pool(llvm::hardware_concurrency(ExecutorConcurrency));
-    for (auto &Group : USRToBitcode) {
-        Pool.async([&]() {
-            std::vector<std::unique_ptr<doc::Info>> Infos;
-
-            for (auto &Bitcode : Group.getValue()) {
-                llvm::BitstreamCursor Stream(Bitcode);
-                doc::ClangDocBitcodeReader Reader(Stream);
-                auto ReadInfos = Reader.readBitcode();
-                if (!ReadInfos) {
-                    llvm::errs() << toString(ReadInfos.takeError()) << "\n";
-                    Error = true;
-                    return;
-                }
-                std::move(ReadInfos->begin(), ReadInfos->end(),
-                          std::back_inserter(Infos));
-            }
-
-            auto Reduced = doc::mergeInfos(Infos);
-            if (!Reduced) {
-                llvm::errs() << llvm::toString(Reduced.takeError());
-                return;
-            }
-
-            // Add a reference to this Info in the Index
-            {
-                std::lock_guard<llvm::sys::Mutex> Guard(IndexMutex);
-                clang::doc::Generator::addInfoToIndex(CDCtx.Idx, Reduced.get().get());
-            }
-
-            // Save in the result map (needs a lock due to threaded access).
-            {
-                std::lock_guard<llvm::sys::Mutex> Guard(USRToInfoMutex);
-                USRToInfo[Group.getKey()] = std::move(Reduced.get());
-            }
-        });
-    }
-
-    Pool.wait();
-
-    if (Error)
-        return 1;
-
-    // Ensure the root output directory exists.
-    if (std::error_code Err = llvm::sys::fs::create_directories(OutDirectory);
-            Err != std::error_code()) {
-        llvm::errs() << "Failed to create directory '" << OutDirectory << "'\n";
-        return 1;
-    }
-
-    // Run the generator.
-    llvm::outs() << "Generating docs...\n";
-    if (auto Err =
-            G->get()->generateDocs(OutDirectory, std::move(USRToInfo), CDCtx)) {
-        llvm::errs() << toString(std::move(Err)) << "\n";
-        return 1;
-    }
-
-    llvm::outs() << "Generating assets for docs...\n";
-    Err = G->get()->createResources(CDCtx);
-    if (Err) {
-        llvm::errs() << toString(std::move(Err)) << "\n";
-        return 1;
-    }
-
-    return 0;
+        std::move(ReadInfos->begin(), ReadInfos->end(),
+                  std::back_inserter(Infos));
+      }
+
+      auto Reduced = doc::mergeInfos(Infos);
+      if (!Reduced) {
+        llvm::errs() << llvm::toString(Reduced.takeError());
+        return;
+      }
+
+      // Add a reference to this Info in the Index
+      {
+        std::lock_guard<llvm::sys::Mutex> Guard(IndexMutex);
+        clang::doc::Generator::addInfoToIndex(CDCtx.Idx, Reduced.get().get());
+      }
+
+      // Save in the result map (needs a lock due to threaded access).
+      {
+        std::lock_guard<llvm::sys::Mutex> Guard(USRToInfoMutex);
+        USRToInfo[Group.getKey()] = std::move(Reduced.get());
+      }
+    });
+  }
+
+  Pool.wait();
+
+  if (Error)
+    return 1;
+
+  // Ensure the root output directory exists.
+  if (std::error_code Err = llvm::sys::fs::create_directories(OutDirectory);
+      Err != std::error_code()) {
+    llvm::errs() << "Failed to create directory '" << OutDirectory << "'\n";
+    return 1;
+  }
+
+  // Run the generator.
+  llvm::outs() << "Generating docs...\n";
+  if (auto Err =
+          G->get()->generateDocs(OutDirectory, std::move(USRToInfo), CDCtx)) {
+    llvm::errs() << toString(std::move(Err)) << "\n";
+    return 1;
+  }
+
+  llvm::outs() << "Generating assets for docs...\n";
+  Err = G->get()->createResources(CDCtx);
+  if (Err) {
+    llvm::errs() << toString(std::move(Err)) << "\n";
+    return 1;
+  }
+
+  return 0;
 }

``````````

</details>


https://github.com/llvm/llvm-project/pull/94717


More information about the cfe-commits mailing list