[clang-tools-extra] [clang-doc] Refactor error handling to use ExitOnError (PR #141699)
Samarth Narang via cfe-commits
cfe-commits at lists.llvm.org
Fri May 30 10:59:44 PDT 2025
https://github.com/snarang181 updated https://github.com/llvm/llvm-project/pull/141699
>From f0b3184f2d4342eb0aacf3a77671556ac2e57650 Mon Sep 17 00:00:00 2001
From: Samarth Narang <snarang at umass.edu>
Date: Tue, 27 May 2025 21:32:41 -0400
Subject: [PATCH 01/17] [clang-doc] Refactor error handling to use ExitOnError
This patch replaces manual error checks and exit() calls in clang-doc
with llvm::ExitOnError for consistency and maintainability.
No functional changes to outputs or APIs.
---
.../clang-doc/tool/ClangDocMain.cpp | 32 ++++++-------------
1 file changed, 10 insertions(+), 22 deletions(-)
diff --git a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
index 41fbe87a713d9..54c5d41e3a6cd 100644
--- a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
+++ b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
@@ -43,6 +43,7 @@
using namespace clang::ast_matchers;
using namespace clang::tooling;
using namespace clang;
+static llvm::ExitOnError ExitOnErr;
static llvm::cl::extrahelp CommonHelp(CommonOptionsParser::HelpMessage);
static llvm::cl::OptionCategory ClangDocCategory("clang-doc options");
@@ -249,6 +250,8 @@ int main(int argc, const char **argv) {
llvm::sys::PrintStackTraceOnErrorSignal(argv[0]);
std::error_code OK;
+ ExitOnErr.setBanner("clang-doc error: ");
+
const char *Overview =
R"(Generates documentation from source code and comments.
@@ -272,11 +275,7 @@ Example usage for a project using a compile commands database:
// 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 G = ExitOnErr(doc::findGeneratorByName(Format));
ArgumentsAdjuster ArgAdjuster;
if (!DoxygenOnly)
@@ -297,10 +296,7 @@ Example usage for a project using a compile commands database:
{UserStylesheets.begin(), UserStylesheets.end()}};
if (Format == "html") {
- if (auto Err = getHtmlAssetFiles(argv[0], CDCtx)) {
- llvm::errs() << toString(std::move(Err)) << "\n";
- return 1;
- }
+ ExitOnErr(getHtmlAssetFiles(argv[0], CDCtx));
}
if (Format == "mustache") {
@@ -320,7 +316,7 @@ Example usage for a project using a compile commands database:
"these files and continue:\n"
<< toString(std::move(Err)) << "\n";
else {
- llvm::errs() << toString(std::move(Err)) << "\n";
+ ExitOnErr(std::move(Err));
return 1;
}
}
@@ -391,22 +387,14 @@ Example usage for a project using a compile commands database:
sortUsrToInfo(USRToInfo);
// 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;
- }
+ ExitOnErr(
+ llvm::errorCodeToError(llvm::sys::fs::create_directories(OutDirectory)));
// 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;
- }
-
+ ExitOnErr(G->generateDocs(OutDirectory, std::move(USRToInfo), CDCtx));
llvm::outs() << "Generating assets for docs...\n";
- Err = G->get()->createResources(CDCtx);
+ Err = G->createResources(CDCtx);
if (Err) {
llvm::outs() << "warning: " << toString(std::move(Err)) << "\n";
}
>From daab868b8bc145286af02867b24175b6cb9edd0e Mon Sep 17 00:00:00 2001
From: Samarth Narang <snarang at umass.edu>
Date: Wed, 28 May 2025 18:47:17 -0400
Subject: [PATCH 02/17] Addressing PR feedback
---
clang-tools-extra/clang-doc/tool/ClangDocMain.cpp | 12 +++++++++---
.../test/clang-doc/invalid-file-error.test | 4 ++++
2 files changed, 13 insertions(+), 3 deletions(-)
create mode 100644 clang-tools-extra/test/clang-doc/invalid-file-error.test
diff --git a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
index 54c5d41e3a6cd..932a9654b563a 100644
--- a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
+++ b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
@@ -43,7 +43,6 @@
using namespace clang::ast_matchers;
using namespace clang::tooling;
using namespace clang;
-static llvm::ExitOnError ExitOnErr;
static llvm::cl::extrahelp CommonHelp(CommonOptionsParser::HelpMessage);
static llvm::cl::OptionCategory ClangDocCategory("clang-doc options");
@@ -119,6 +118,8 @@ static llvm::cl::opt<OutputFormatTy> FormatEnum(
"Documentation in mustache HTML format")),
llvm::cl::init(OutputFormatTy::yaml), llvm::cl::cat(ClangDocCategory));
+static llvm::ExitOnError ExitOnErr;
+
static std::string getFormatString() {
switch (FormatEnum) {
case OutputFormatTy::yaml:
@@ -387,8 +388,13 @@ Example usage for a project using a compile commands database:
sortUsrToInfo(USRToInfo);
// Ensure the root output directory exists.
- ExitOnErr(
- llvm::errorCodeToError(llvm::sys::fs::create_directories(OutDirectory)));
+ if (std::error_code Err = llvm::sys::fs::create_directories(OutDirectory);
+ Err != std::error_code()) {
+ ExitOnErr(llvm::createStringError(
+ llvm::inconvertibleErrorCode(), "Failed to create directory '%s': %s",
+ OutDirectory.c_str(), Err.message().c_str()));
+ }
+
// Run the generator.
llvm::outs() << "Generating docs...\n";
diff --git a/clang-tools-extra/test/clang-doc/invalid-file-error.test b/clang-tools-extra/test/clang-doc/invalid-file-error.test
new file mode 100644
index 0000000000000..8d391842aa452
--- /dev/null
+++ b/clang-tools-extra/test/clang-doc/invalid-file-error.test
@@ -0,0 +1,4 @@
+// RUN: not clang-doc %S/Inputs/basic-project/src/Circle.cpp -output=/root/docs 2>&1 | FileCheck %s
+
+// CHECK: clang-doc error: Failed to create directory
+
>From 05328e9c8edcdfb12d201ae8d7786288c1174325 Mon Sep 17 00:00:00 2001
From: Samarth Narang <snarang at umass.edu>
Date: Wed, 28 May 2025 20:24:36 -0400
Subject: [PATCH 03/17] Clang-format fixes
---
clang-tools-extra/clang-doc/tool/ClangDocMain.cpp | 1 -
1 file changed, 1 deletion(-)
diff --git a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
index 932a9654b563a..72a748e756db7 100644
--- a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
+++ b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
@@ -395,7 +395,6 @@ Example usage for a project using a compile commands database:
OutDirectory.c_str(), Err.message().c_str()));
}
-
// Run the generator.
llvm::outs() << "Generating docs...\n";
ExitOnErr(G->generateDocs(OutDirectory, std::move(USRToInfo), CDCtx));
>From fb8ca572c3da67be5896d7ad38b288ef0ebbc7a2 Mon Sep 17 00:00:00 2001
From: Samarth Narang <snarang at umass.edu>
Date: Thu, 29 May 2025 06:26:07 -0400
Subject: [PATCH 04/17] Use more relevant file system API for error handling
Address issue with the lit tests
---
clang-tools-extra/clang-doc/tool/ClangDocMain.cpp | 7 ++-----
.../test/clang-doc/invalid-file-error.test | 12 ++++++++++--
2 files changed, 12 insertions(+), 7 deletions(-)
diff --git a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
index 72a748e756db7..6c93136a63148 100644
--- a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
+++ b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
@@ -388,11 +388,8 @@ Example usage for a project using a compile commands database:
sortUsrToInfo(USRToInfo);
// Ensure the root output directory exists.
- if (std::error_code Err = llvm::sys::fs::create_directories(OutDirectory);
- Err != std::error_code()) {
- ExitOnErr(llvm::createStringError(
- llvm::inconvertibleErrorCode(), "Failed to create directory '%s': %s",
- OutDirectory.c_str(), Err.message().c_str()));
+ if (std::error_code Err = llvm::sys::fs::create_directories(OutDirectory)) {
+ ExitOnErr(llvm::createFileError(OutDirectory, Err));
}
// Run the generator.
diff --git a/clang-tools-extra/test/clang-doc/invalid-file-error.test b/clang-tools-extra/test/clang-doc/invalid-file-error.test
index 8d391842aa452..8c045e9819b71 100644
--- a/clang-tools-extra/test/clang-doc/invalid-file-error.test
+++ b/clang-tools-extra/test/clang-doc/invalid-file-error.test
@@ -1,4 +1,12 @@
-// RUN: not clang-doc %S/Inputs/basic-project/src/Circle.cpp -output=/root/docs 2>&1 | FileCheck %s
+// Test: Invalid output path (%t is a file, not a directory)
+// RUN: rm -rf %t && echo "not a dir" > %t
+// RUN: not clang-doc %s -output=%t/subdir 2>&1 | FileCheck --check-prefix=BAD-OUTPUT %s
-// CHECK: clang-doc error: Failed to create directory
+// BAD-OUTPUT: clang-doc error:
+// BAD-OUTPUT: Not a directory
+//
+// Test: Invalid format option
+// RUN: not clang-doc %s -format=badformat 2>&1 | FileCheck --check-prefix=BAD-FORMAT %s
+
+// BAD-FORMAT: clang-doc: for the --format option: Cannot find option named 'badformat'!
\ No newline at end of file
>From 76140a2eb7a0bff5c769d54a220fe81f2b041d75 Mon Sep 17 00:00:00 2001
From: Samarth Narang <snarang at umass.edu>
Date: Thu, 29 May 2025 06:27:23 -0400
Subject: [PATCH 05/17] Formatting commit
---
clang-tools-extra/clang-doc/tool/ClangDocMain.cpp | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
index 6c93136a63148..80b583e47c95b 100644
--- a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
+++ b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
@@ -389,7 +389,7 @@ Example usage for a project using a compile commands database:
// Ensure the root output directory exists.
if (std::error_code Err = llvm::sys::fs::create_directories(OutDirectory)) {
- ExitOnErr(llvm::createFileError(OutDirectory, Err));
+ ExitOnErr(llvm::createFileError(OutDirectory, Err));
}
// Run the generator.
>From abdae4716deab65e023548734a2882bad31b0f46 Mon Sep 17 00:00:00 2001
From: Samarth Narang <snarang at umass.edu>
Date: Thu, 29 May 2025 06:29:03 -0400
Subject: [PATCH 06/17] Rename test file to reflect multiple test cases
---
.../clang-doc/{invalid-file-error.test => invalid-options.cpp} | 0
1 file changed, 0 insertions(+), 0 deletions(-)
rename clang-tools-extra/test/clang-doc/{invalid-file-error.test => invalid-options.cpp} (100%)
diff --git a/clang-tools-extra/test/clang-doc/invalid-file-error.test b/clang-tools-extra/test/clang-doc/invalid-options.cpp
similarity index 100%
rename from clang-tools-extra/test/clang-doc/invalid-file-error.test
rename to clang-tools-extra/test/clang-doc/invalid-options.cpp
>From 7449a52f01ec5a9161a1dbed2ed1ede7eba49afb Mon Sep 17 00:00:00 2001
From: Samarth Narang <snarang at umass.edu>
Date: Thu, 29 May 2025 09:07:59 -0400
Subject: [PATCH 07/17] Modifying expected result to iron out cross-platform
output diff
---
clang-tools-extra/test/clang-doc/invalid-options.cpp | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/clang-tools-extra/test/clang-doc/invalid-options.cpp b/clang-tools-extra/test/clang-doc/invalid-options.cpp
index 8c045e9819b71..9518b9640b20b 100644
--- a/clang-tools-extra/test/clang-doc/invalid-options.cpp
+++ b/clang-tools-extra/test/clang-doc/invalid-options.cpp
@@ -3,7 +3,7 @@
// RUN: not clang-doc %s -output=%t/subdir 2>&1 | FileCheck --check-prefix=BAD-OUTPUT %s
// BAD-OUTPUT: clang-doc error:
-// BAD-OUTPUT: Not a directory
+// BAD-OUTPUT: {{(Not a directory|no such file or directory)}}
//
// Test: Invalid format option
>From 497d6d46b0201b3069333d418cca4363e1b446c8 Mon Sep 17 00:00:00 2001
From: Samarth Narang <snarang at umass.edu>
Date: Thu, 29 May 2025 19:49:00 -0400
Subject: [PATCH 08/17] Modifications in ClangDocMain.cpp to handle new rebased
code Some more cleanup -- redundant code removed Cleanup of test cases
according to conventions
---
.../clang-doc/tool/ClangDocMain.cpp | 11 ++---------
.../test/clang-doc/invalid-options.cpp | 19 ++++++++-----------
2 files changed, 10 insertions(+), 20 deletions(-)
diff --git a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
index 80b583e47c95b..ccbd3640ec0bc 100644
--- a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
+++ b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
@@ -301,10 +301,7 @@ Example usage for a project using a compile commands database:
}
if (Format == "mustache") {
- if (auto Err = getMustacheHtmlFiles(argv[0], CDCtx)) {
- llvm::errs() << toString(std::move(Err)) << "\n";
- return 1;
- }
+ ExitOnErr(getMustacheHtmlFiles(argv[0], CDCtx));
}
// Mapping phase
@@ -318,7 +315,6 @@ Example usage for a project using a compile commands database:
<< toString(std::move(Err)) << "\n";
else {
ExitOnErr(std::move(Err));
- return 1;
}
}
@@ -396,10 +392,7 @@ Example usage for a project using a compile commands database:
llvm::outs() << "Generating docs...\n";
ExitOnErr(G->generateDocs(OutDirectory, std::move(USRToInfo), CDCtx));
llvm::outs() << "Generating assets for docs...\n";
- Err = G->createResources(CDCtx);
- if (Err) {
- llvm::outs() << "warning: " << toString(std::move(Err)) << "\n";
- }
+ ExitOnErr(G->createResources(CDCtx));
return 0;
}
diff --git a/clang-tools-extra/test/clang-doc/invalid-options.cpp b/clang-tools-extra/test/clang-doc/invalid-options.cpp
index 9518b9640b20b..186f019c7ceae 100644
--- a/clang-tools-extra/test/clang-doc/invalid-options.cpp
+++ b/clang-tools-extra/test/clang-doc/invalid-options.cpp
@@ -1,12 +1,9 @@
-// Test: Invalid output path (%t is a file, not a directory)
-// RUN: rm -rf %t && echo "not a dir" > %t
-// RUN: not clang-doc %s -output=%t/subdir 2>&1 | FileCheck --check-prefix=BAD-OUTPUT %s
+/// Invalid output path (%t is a file, not a directory)
+// RUN: rm -rf %t && touch %t
+// RUN: not clang-doc %s -output=%t/subdir 2>&1 | FileCheck %s
+// CHECK: clang-doc error:
+// CHECK: {{(Not a directory|no such file or directory)}}
-// BAD-OUTPUT: clang-doc error:
-// BAD-OUTPUT: {{(Not a directory|no such file or directory)}}
-
-//
-// Test: Invalid format option
-// RUN: not clang-doc %s -format=badformat 2>&1 | FileCheck --check-prefix=BAD-FORMAT %s
-
-// BAD-FORMAT: clang-doc: for the --format option: Cannot find option named 'badformat'!
\ No newline at end of file
+/// Invalid format option
+// RUN: not clang-doc %s -format=badformat 2>&1 | FileCheck %s --check-prefix=BAD-FORMAT
+// BAD-FORMAT: clang-doc: for the --format option: Cannot find option named 'badformat'!
>From f57b3cff4857616a554a0d02c9b26303e2eaab0f Mon Sep 17 00:00:00 2001
From: Samarth Narang <snarang at umass.edu>
Date: Thu, 29 May 2025 20:25:46 -0400
Subject: [PATCH 09/17] Add more test cases for clang-doc failures
---
.../test/clang-doc/invalid-options.cpp | 19 +++++++++++++++++--
1 file changed, 17 insertions(+), 2 deletions(-)
diff --git a/clang-tools-extra/test/clang-doc/invalid-options.cpp b/clang-tools-extra/test/clang-doc/invalid-options.cpp
index 186f019c7ceae..e9b64f605f181 100644
--- a/clang-tools-extra/test/clang-doc/invalid-options.cpp
+++ b/clang-tools-extra/test/clang-doc/invalid-options.cpp
@@ -1,9 +1,24 @@
-/// Invalid output path (%t is a file, not a directory)
+/// Invalid output path (%t is a file, not a directory).
// RUN: rm -rf %t && touch %t
// RUN: not clang-doc %s -output=%t/subdir 2>&1 | FileCheck %s
// CHECK: clang-doc error:
// CHECK: {{(Not a directory|no such file or directory)}}
-/// Invalid format option
+/// Invalid format option.
// RUN: not clang-doc %s -format=badformat 2>&1 | FileCheck %s --check-prefix=BAD-FORMAT
// BAD-FORMAT: clang-doc: for the --format option: Cannot find option named 'badformat'!
+
+/// Missing HTML asset directory (warning only).
+// RUN: clang-doc %s -format=html -asset=%t/nonexistent-assets 2>&1 | FileCheck %s --check-prefix=ASSET-WARN
+// ASSET-WARN: Asset path supply is not a directory
+// ASSET-WARN: falling back to default
+
+/// Mapping failure (with --ignore-map-errors=false).
+// RUN: not clang-doc %t/nonexistent.cpp -ignore-map-errors=false 2>&1 | FileCheck %s --check-prefix=MAP-FAIL
+// MAP-FAIL: clang-doc error: Failed to run action
+
+/// Mapping failure (with --ignore-map-errors=true).
+// RUN: clang-doc %t/nonexistent.cpp 2>&1 | FileCheck %s --check-prefix=MAP-WARN
+// MAP-WARN: Error mapping decls in files. Clang-doc will ignore these files and continue
+
+///TODO: Add tests for failures in generateDocs() and in createResources().
>From 1a41b0f6544de2af452472e4b598508a99dc1215 Mon Sep 17 00:00:00 2001
From: Samarth Narang <snarang at umass.edu>
Date: Thu, 29 May 2025 21:39:31 -0400
Subject: [PATCH 10/17] Add explicit output dir in test case
---
clang-tools-extra/test/clang-doc/invalid-options.cpp | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/clang-tools-extra/test/clang-doc/invalid-options.cpp b/clang-tools-extra/test/clang-doc/invalid-options.cpp
index e9b64f605f181..912144c0773fe 100644
--- a/clang-tools-extra/test/clang-doc/invalid-options.cpp
+++ b/clang-tools-extra/test/clang-doc/invalid-options.cpp
@@ -5,7 +5,7 @@
// CHECK: {{(Not a directory|no such file or directory)}}
/// Invalid format option.
-// RUN: not clang-doc %s -format=badformat 2>&1 | FileCheck %s --check-prefix=BAD-FORMAT
+// RUN: not clang-doc %s --output=%t.dir -format=badformat 2>&1 | FileCheck %s --check-prefix=BAD-FORMAT
// BAD-FORMAT: clang-doc: for the --format option: Cannot find option named 'badformat'!
/// Missing HTML asset directory (warning only).
>From 49da3277a1651a6123ea22c98234b31bc9fbde51 Mon Sep 17 00:00:00 2001
From: Samarth Narang <snarang at umass.edu>
Date: Thu, 29 May 2025 21:56:24 -0400
Subject: [PATCH 11/17] Wrap executor in ExitOnErr and modify uses Add test
case
---
.../clang-doc/tool/ClangDocMain.cpp | 41 ++++++++++---------
.../test/clang-doc/invalid-options.cpp | 5 +++
2 files changed, 27 insertions(+), 19 deletions(-)
diff --git a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
index ccbd3640ec0bc..25fd9a94dd387 100644
--- a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
+++ b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
@@ -247,6 +247,22 @@ sortUsrToInfo(llvm::StringMap<std::unique_ptr<doc::Info>> &USRToInfo) {
}
}
+llvm::Error runMappingPhase(tooling::ToolExecutor *Executor,
+ clang::doc::ClangDocContext &CDCtx, tooling::ArgumentsAdjuster &ArgAdjuster, bool IgnoreMappingFailures ) {
+ auto Err =
+ Executor->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";
+ return llvm::Error::success();
+ }
+ return Err;
+ }
+ return llvm::Error::success();
+}
+
int main(int argc, const char **argv) {
llvm::sys::PrintStackTraceOnErrorSignal(argv[0]);
std::error_code OK;
@@ -265,13 +281,10 @@ 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);
+ auto Executor = ExitOnErr(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();
@@ -286,7 +299,7 @@ Example usage for a project using a compile commands database:
ArgAdjuster);
clang::doc::ClangDocContext CDCtx = {
- Executor->get()->getExecutionContext(),
+ Executor->getExecutionContext(),
ProjectName,
PublicOnly,
OutDirectory,
@@ -306,24 +319,14 @@ Example usage for a project using a compile commands database:
// 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 {
- ExitOnErr(std::move(Err));
- }
- }
+ ExitOnErr(runMappingPhase(Executor.get(), CDCtx, ArgAdjuster, IgnoreMappingFailures));
// 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(
+ Executor->getToolResults()->forEachResult(
[&](StringRef Key, StringRef Value) {
USRToBitcode[Key].emplace_back(Value);
});
diff --git a/clang-tools-extra/test/clang-doc/invalid-options.cpp b/clang-tools-extra/test/clang-doc/invalid-options.cpp
index 912144c0773fe..9cbf95143537f 100644
--- a/clang-tools-extra/test/clang-doc/invalid-options.cpp
+++ b/clang-tools-extra/test/clang-doc/invalid-options.cpp
@@ -21,4 +21,9 @@
// RUN: clang-doc %t/nonexistent.cpp 2>&1 | FileCheck %s --check-prefix=MAP-WARN
// MAP-WARN: Error mapping decls in files. Clang-doc will ignore these files and continue
+///Invalid executor type
+// RUN: not clang-doc --executor=invalid %s 2>&1 | FileCheck %s --check-prefix=EXECUTOR-FAIL
+// EXECUTOR-FAIL: clang-doc error:
+// EXECUTOR-FAIL: Executor "invalid" is not registered
+
///TODO: Add tests for failures in generateDocs() and in createResources().
>From 2657c20de15d12a0a61c4433775c0fdeb8876caf Mon Sep 17 00:00:00 2001
From: Samarth Narang <snarang at umass.edu>
Date: Thu, 29 May 2025 21:57:08 -0400
Subject: [PATCH 12/17] Run clang-format
---
clang-tools-extra/clang-doc/tool/ClangDocMain.cpp | 14 +++++++-------
1 file changed, 7 insertions(+), 7 deletions(-)
diff --git a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
index 25fd9a94dd387..8341f501c1009 100644
--- a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
+++ b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
@@ -248,9 +248,10 @@ sortUsrToInfo(llvm::StringMap<std::unique_ptr<doc::Info>> &USRToInfo) {
}
llvm::Error runMappingPhase(tooling::ToolExecutor *Executor,
- clang::doc::ClangDocContext &CDCtx, tooling::ArgumentsAdjuster &ArgAdjuster, bool IgnoreMappingFailures ) {
- auto Err =
- Executor->execute(doc::newMapperActionFactory(CDCtx), ArgAdjuster);
+ clang::doc::ClangDocContext &CDCtx,
+ tooling::ArgumentsAdjuster &ArgAdjuster,
+ bool IgnoreMappingFailures) {
+ auto Err = Executor->execute(doc::newMapperActionFactory(CDCtx), ArgAdjuster);
if (Err) {
if (IgnoreMappingFailures) {
llvm::errs() << "Error mapping decls in files. Clang-doc will ignore "
@@ -282,9 +283,7 @@ Example usage for a project using a compile commands database:
)";
auto Executor = ExitOnErr(clang::tooling::createExecutorFromCommandLineArgs(
- argc, argv, ClangDocCategory, Overview));
-
-
+ argc, argv, ClangDocCategory, Overview));
// Fail early if an invalid format was provided.
std::string Format = getFormatString();
@@ -319,7 +318,8 @@ Example usage for a project using a compile commands database:
// Mapping phase
llvm::outs() << "Mapping decls...\n";
- ExitOnErr(runMappingPhase(Executor.get(), CDCtx, ArgAdjuster, IgnoreMappingFailures));
+ ExitOnErr(runMappingPhase(Executor.get(), CDCtx, ArgAdjuster,
+ IgnoreMappingFailures));
// Collect values into output by key.
// In ToolResults, the Key is the hashed USR and the value is the
>From 49d039b802c8ec1f4b86f31549ca9dbef393ce05 Mon Sep 17 00:00:00 2001
From: Samarth Narang <snarang at umass.edu>
Date: Fri, 30 May 2025 07:11:18 -0400
Subject: [PATCH 13/17] Add helper for handling mapping phase errors
---
.../clang-doc/tool/ClangDocMain.cpp | 29 +++++++++----------
1 file changed, 13 insertions(+), 16 deletions(-)
diff --git a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
index 8341f501c1009..6e59eeb252ae6 100644
--- a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
+++ b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
@@ -247,21 +247,17 @@ sortUsrToInfo(llvm::StringMap<std::unique_ptr<doc::Info>> &USRToInfo) {
}
}
-llvm::Error runMappingPhase(tooling::ToolExecutor *Executor,
- clang::doc::ClangDocContext &CDCtx,
- tooling::ArgumentsAdjuster &ArgAdjuster,
- bool IgnoreMappingFailures) {
- auto Err = Executor->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";
- return llvm::Error::success();
- }
- return Err;
+llvm::Error handleMappingPhaseErrors(llvm::Error Err,
+ bool IgnoreMappingFailures) {
+ if (!Err)
+ return llvm::Error::success();
+ if (IgnoreMappingFailures) {
+ llvm::errs() << "Error mapping decls in files. Clang-doc will ignore these "
+ "files and continue:\n"
+ << toString(std::move(Err)) << "\n";
+ return llvm::Error::success();
}
- return llvm::Error::success();
+ return Err;
}
int main(int argc, const char **argv) {
@@ -318,8 +314,9 @@ Example usage for a project using a compile commands database:
// Mapping phase
llvm::outs() << "Mapping decls...\n";
- ExitOnErr(runMappingPhase(Executor.get(), CDCtx, ArgAdjuster,
- IgnoreMappingFailures));
+ ExitOnErr(handleMappingPhaseErrors(
+ Executor->execute(doc::newMapperActionFactory(CDCtx), ArgAdjuster),
+ IgnoreMappingFailures));
// Collect values into output by key.
// In ToolResults, the Key is the hashed USR and the value is the
>From 94ca232b33797fd747f4bb8bc0832df283df5560 Mon Sep 17 00:00:00 2001
From: Samarth Narang <snarang at umass.edu>
Date: Fri, 30 May 2025 07:26:30 -0400
Subject: [PATCH 14/17] Incorporating suggestions in the lit test
---
clang-tools-extra/test/clang-doc/invalid-options.cpp | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/clang-tools-extra/test/clang-doc/invalid-options.cpp b/clang-tools-extra/test/clang-doc/invalid-options.cpp
index 9cbf95143537f..c8a4cef8364eb 100644
--- a/clang-tools-extra/test/clang-doc/invalid-options.cpp
+++ b/clang-tools-extra/test/clang-doc/invalid-options.cpp
@@ -1,17 +1,17 @@
/// Invalid output path (%t is a file, not a directory).
// RUN: rm -rf %t && touch %t
-// RUN: not clang-doc %s -output=%t/subdir 2>&1 | FileCheck %s
-// CHECK: clang-doc error:
-// CHECK: {{(Not a directory|no such file or directory)}}
+// RUN: not clang-doc %s -output=%t/subdir 2>&1 | FileCheck %s --check-prefix=OUTPUT-FAIL
+// OUTPUT-FAIL: clang-doc error:
+// OUTPUT-FAIL: {{(Not a directory|no such file or directory)}}
/// Invalid format option.
-// RUN: not clang-doc %s --output=%t.dir -format=badformat 2>&1 | FileCheck %s --check-prefix=BAD-FORMAT
+// RUN: rm -rf %t && mkdir %t && touch %t/file
+// RUN: not clang-doc %s --output=%t/file -format=badformat 2>&1 | FileCheck %s --check-prefix=BAD-FORMAT
// BAD-FORMAT: clang-doc: for the --format option: Cannot find option named 'badformat'!
/// Missing HTML asset directory (warning only).
// RUN: clang-doc %s -format=html -asset=%t/nonexistent-assets 2>&1 | FileCheck %s --check-prefix=ASSET-WARN
// ASSET-WARN: Asset path supply is not a directory
-// ASSET-WARN: falling back to default
/// Mapping failure (with --ignore-map-errors=false).
// RUN: not clang-doc %t/nonexistent.cpp -ignore-map-errors=false 2>&1 | FileCheck %s --check-prefix=MAP-FAIL
>From 1ff0f91bf71532f009d3149783a9771b3c37a0c4 Mon Sep 17 00:00:00 2001
From: Samarth Narang <snarang at umass.edu>
Date: Fri, 30 May 2025 07:32:30 -0400
Subject: [PATCH 15/17] Add helper function for handling error handling in case
of output dir existence too
---
clang-tools-extra/clang-doc/tool/ClangDocMain.cpp | 12 +++++++++---
1 file changed, 9 insertions(+), 3 deletions(-)
diff --git a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
index 6e59eeb252ae6..da75c21864cd7 100644
--- a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
+++ b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
@@ -260,6 +260,14 @@ llvm::Error handleMappingPhaseErrors(llvm::Error Err,
return Err;
}
+llvm::Error ensureOutputDirExists(const std::string &OutDirectory) {
+ // Ensure the root output directory exists.
+ if (std::error_code Err = llvm::sys::fs::create_directories(OutDirectory)) {
+ return llvm::createFileError(OutDirectory, Err);
+ }
+ return llvm::Error::success();
+}
+
int main(int argc, const char **argv) {
llvm::sys::PrintStackTraceOnErrorSignal(argv[0]);
std::error_code OK;
@@ -384,9 +392,7 @@ Example usage for a project using a compile commands database:
sortUsrToInfo(USRToInfo);
// Ensure the root output directory exists.
- if (std::error_code Err = llvm::sys::fs::create_directories(OutDirectory)) {
- ExitOnErr(llvm::createFileError(OutDirectory, Err));
- }
+ ExitOnErr(ensureOutputDirExists(OutDirectory));
// Run the generator.
llvm::outs() << "Generating docs...\n";
>From 66e9d5e8c4b953562e9bbb12e936916f9884bec8 Mon Sep 17 00:00:00 2001
From: Samarth Narang <snarang at umass.edu>
Date: Fri, 30 May 2025 07:34:21 -0400
Subject: [PATCH 16/17] Remove same comment
---
clang-tools-extra/clang-doc/tool/ClangDocMain.cpp | 1 -
1 file changed, 1 deletion(-)
diff --git a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
index da75c21864cd7..f99427aabac9e 100644
--- a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
+++ b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
@@ -261,7 +261,6 @@ llvm::Error handleMappingPhaseErrors(llvm::Error Err,
}
llvm::Error ensureOutputDirExists(const std::string &OutDirectory) {
- // Ensure the root output directory exists.
if (std::error_code Err = llvm::sys::fs::create_directories(OutDirectory)) {
return llvm::createFileError(OutDirectory, Err);
}
>From 74abce843aa2a67bcf7969e30a5f8249bcea2ccb Mon Sep 17 00:00:00 2001
From: Samarth Narang <snarang at umass.edu>
Date: Fri, 30 May 2025 13:55:11 -0400
Subject: [PATCH 17/17] Renaming functions, making them static, some more
cleanup
---
clang-tools-extra/clang-doc/tool/ClangDocMain.cpp | 15 ++++++---------
1 file changed, 6 insertions(+), 9 deletions(-)
diff --git a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
index f99427aabac9e..8253ef298db4d 100644
--- a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
+++ b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
@@ -247,8 +247,7 @@ sortUsrToInfo(llvm::StringMap<std::unique_ptr<doc::Info>> &USRToInfo) {
}
}
-llvm::Error handleMappingPhaseErrors(llvm::Error Err,
- bool IgnoreMappingFailures) {
+static llvm::Error handleMappingFailures(llvm::Error Err) {
if (!Err)
return llvm::Error::success();
if (IgnoreMappingFailures) {
@@ -260,10 +259,9 @@ llvm::Error handleMappingPhaseErrors(llvm::Error Err,
return Err;
}
-llvm::Error ensureOutputDirExists(const std::string &OutDirectory) {
- if (std::error_code Err = llvm::sys::fs::create_directories(OutDirectory)) {
+static llvm::Error createDirectories(llvm::StringRef OutDirectory) {
+ if (std::error_code Err = llvm::sys::fs::create_directories(OutDirectory))
return llvm::createFileError(OutDirectory, Err);
- }
return llvm::Error::success();
}
@@ -321,9 +319,8 @@ Example usage for a project using a compile commands database:
// Mapping phase
llvm::outs() << "Mapping decls...\n";
- ExitOnErr(handleMappingPhaseErrors(
- Executor->execute(doc::newMapperActionFactory(CDCtx), ArgAdjuster),
- IgnoreMappingFailures));
+ ExitOnErr(handleMappingFailures(
+ Executor->execute(doc::newMapperActionFactory(CDCtx), ArgAdjuster)));
// Collect values into output by key.
// In ToolResults, the Key is the hashed USR and the value is the
@@ -391,7 +388,7 @@ Example usage for a project using a compile commands database:
sortUsrToInfo(USRToInfo);
// Ensure the root output directory exists.
- ExitOnErr(ensureOutputDirExists(OutDirectory));
+ ExitOnErr(createDirectories(OutDirectory));
// Run the generator.
llvm::outs() << "Generating docs...\n";
More information about the cfe-commits
mailing list