[clang-tools-extra] ea50901 - [clang-doc] Default to Standalone executor and improve documentation
Petr Hosek via cfe-commits
cfe-commits at lists.llvm.org
Thu Aug 4 10:43:25 PDT 2022
Author: Petr Hosek
Date: 2022-08-04T17:43:16Z
New Revision: ea50901aa9e58fe3750df3e38471e65b027317fc
URL: https://github.com/llvm/llvm-project/commit/ea50901aa9e58fe3750df3e38471e65b027317fc
DIFF: https://github.com/llvm/llvm-project/commit/ea50901aa9e58fe3750df3e38471e65b027317fc.diff
LOG: [clang-doc] Default to Standalone executor and improve documentation
This should provide a more intuitive usage consistent with other tools.
Differential Revision: https://reviews.llvm.org/D130226
Added:
Modified:
clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
clang-tools-extra/docs/ReleaseNotes.rst
clang-tools-extra/docs/clang-doc.rst
Removed:
################################################################################
diff --git a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
index 218e36d9d91e2..fc22e55edfb1a 100644
--- a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
+++ b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
@@ -182,12 +182,23 @@ int main(int argc, const char **argv) {
llvm::sys::PrintStackTraceOnErrorSignal(argv[0]);
std::error_code OK;
- ExecutorName.setInitialValue("all-TUs");
- auto Exec = clang::tooling::createExecutorFromCommandLineArgs(
- argc, argv, ClangDocCategory);
+ const char *Overview =
+ R"(Generates documentation from source code and comments.
- if (!Exec) {
- llvm::errs() << toString(Exec.takeError()) << "\n";
+Example usage for files without flags (default):
+
+ $ clang-doc File1.cpp File2.cpp ... FileN.cpp
+
+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;
}
@@ -208,7 +219,7 @@ int main(int argc, const char **argv) {
ArgAdjuster);
clang::doc::ClangDocContext CDCtx = {
- Exec->get()->getExecutionContext(),
+ Executor->get()->getExecutionContext(),
ProjectName,
PublicOnly,
OutDirectory,
@@ -239,7 +250,7 @@ int main(int argc, const char **argv) {
// Mapping phase
llvm::outs() << "Mapping decls...\n";
auto Err =
- Exec->get()->execute(doc::newMapperActionFactory(CDCtx), ArgAdjuster);
+ Executor->get()->execute(doc::newMapperActionFactory(CDCtx), ArgAdjuster);
if (Err) {
if (IgnoreMappingFailures)
llvm::errs() << "Error mapping decls in files. Clang-doc will ignore "
@@ -256,7 +267,7 @@ int main(int argc, const char **argv) {
// bitcode-encoded representation of the Info object.
llvm::outs() << "Collecting infos...\n";
llvm::StringMap<std::vector<StringRef>> USRToBitcode;
- Exec->get()->getToolResults()->forEachResult(
+ Executor->get()->getToolResults()->forEachResult(
[&](StringRef Key, StringRef Value) {
auto R = USRToBitcode.try_emplace(Key, std::vector<StringRef>());
R.first->second.emplace_back(Value);
diff --git a/clang-tools-extra/docs/ReleaseNotes.rst b/clang-tools-extra/docs/ReleaseNotes.rst
index e645468016e0c..840e3aac32578 100644
--- a/clang-tools-extra/docs/ReleaseNotes.rst
+++ b/clang-tools-extra/docs/ReleaseNotes.rst
@@ -81,7 +81,7 @@ Miscellaneous
Improvements to clang-doc
-------------------------
-The improvements are...
+- The default executor was changed to standalone to match other tools.
Improvements to clang-query
---------------------------
diff --git a/clang-tools-extra/docs/clang-doc.rst b/clang-tools-extra/docs/clang-doc.rst
index bd0a9cacaf011..d65b986c9016d 100644
--- a/clang-tools-extra/docs/clang-doc.rst
+++ b/clang-tools-extra/docs/clang-doc.rst
@@ -25,19 +25,23 @@ compile command database for your project (for an example of how to do this
see `How To Setup Tooling For LLVM
<https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html>`_).
-By default, the tool will run on all files listed in the given compile commands
-database:
+The tool will process a list of files by default:
.. code-block:: console
- $ clang-doc /path/to/compile_commands.json
+ $ clang-doc File1.cpp File2.cpp ... FileN.cpp
-The tool can also be used on a single file or multiple files if a build path is
-passed with the ``-p`` flag.
+The tool can be also used with a compile commands database:
.. code-block:: console
- $ clang-doc /path/to/file.cpp -p /path/to/build
+ $ clang-doc --executor=all-TUs compile_commands.json
+
+To select only a subset of files from the database, use the ``--filter`` flag:
+
+.. code-block:: console
+
+ $ clang-doc --executor=all-TUs --filter=File[0-9]+.cpp compile_commands.json
Output
======
@@ -50,7 +54,7 @@ The top-level directory is configurable through the ``output`` flag:
.. code-block:: console
- $ clang-doc -output=output/directory/ compile_commands.json
+ $ clang-doc --output=output/directory/ compile_commands.json
Configuration
=============
@@ -67,6 +71,16 @@ Options
.. code-block:: console
$ clang-doc --help
+ OVERVIEW: Generates documentation from source code and comments.
+
+ Example usage for files without flags (default):
+
+ $ clang-doc File1.cpp File2.cpp ... FileN.cpp
+
+ Example usage for a project using a compile commands database:
+
+ $ clang-doc --executor=all-TUs compile_commands.json
+
USAGE: clang-doc [options] <source0> [... <sourceN>]
OPTIONS:
More information about the cfe-commits
mailing list