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: _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
