[clang-doc] Default to Standalone executor and improve documentation

[phosek]

Summary

This should provide a more intuitive usage consistent with other tools.

[paulkirth]

LGTM w/ the caveat that I think we should update the release notes, since we're changing the default behavior of a command line tool. I've also left a few small suggestions the wording.

clang-tools-extra/clang-doc/tool/ClangDocMain.cpp

188–201

192

clang-tools-extra/docs/clang-doc.rst

28

34

77

81

[abrachet]

clang-tools-extra/clang-doc/tool/ClangDocMain.cpp

195

Is it intentional that the rest of this help message also has two spaces before the text? It seems like the only other Overview passed to createExecutorFromCommandLineArgs in clangd has the same formatting. It also has the trailing whitespace on newline, but I don't think it should

clang-tools-extra/clang-doc/tool/ClangDocMain.cpp

llvm::Expected<llvm::SmallString<128>> getInfoOutputFile(StringRef Root,
   llvm::sys::path::append(Path, Name + Ext);
   return Path;
 }
 
 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;
   }
 
   // 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 = {
-      Exec->get()->getExecutionContext(),
+      Executor->get()->getExecutionContext(),
       ProjectName,
       PublicOnly,
       OutDirectory,
       SourceRoot,
       RepositoryUrl,
       {UserStylesheets.begin(), UserStylesheets.end()},
       {"index.js", "index_json.js"}};
 
if (Format == "html") {
     CDCtx.UserStylesheets.insert(CDCtx.UserStylesheets.begin(),
                                  std::string(DefaultStylesheet.str()));
     CDCtx.FilesToCopy.emplace_back(IndexJS.str());
   }
 
   // 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 "
                       "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;
-  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);
       });
 
   // First reducing phase (reduce all decls into one info per decl).
   llvm::outs() << "Reducing " << USRToBitcode.size() << " infos...\n";
   std::atomic<bool> Error;

clang-tools-extra/docs/ReleaseNotes.rst

 ^^^^^^^^^^^
 
 Miscellaneous
 ^^^^^^^^^^^^^
 
 Improvements to clang-doc
 -------------------------
 
-The improvements are...
+- The default executor was changed to standalone to match other tools.
 
 Improvements to clang-query
 ---------------------------
 
 The improvements are...
 
 Improvements to clang-rename
 ----------------------------

clang-tools-extra/docs/clang-doc.rst

 ===
 
 :program:`clang-doc` is a `LibTooling
 <https://clang.llvm.org/docs/LibTooling.html>`_-based tool, and so requires a
 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
 ======
 
 :program:`clang-doc` produces a directory of documentation. One file is produced
 for each namespace and record in the project source code, containing all
 documentation (including contained functions, methods, and enums) for that item.
 
 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
 =============
 
 Configuration for :program:`clang-doc` is currently limited to command-line options.
 In the future, it may develop the ability to use a configuration file, but no such
 efforts are currently in progress.
 
 Options
 -------
 
 :program:`clang-doc` offers the following 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:
 
   Generic Options:
 
     -help                      - Display available options (-help-hidden for more)
     -help-list                 - Display list of available options (-help-list-hidden for more)