[clang] [clang-tools-extra] [clang] Don't add documentation comments to the AST if not requested (PR #206363)
via cfe-commits
cfe-commits at lists.llvm.org
Sun Jun 28 23:40:51 PDT 2026
https://github.com/AnonMiraj updated https://github.com/llvm/llvm-project/pull/206363
>From ba4ada54cbed3d44680a0811c261536a1021f2f6 Mon Sep 17 00:00:00 2001
From: Anonmiraj <ezzibrahimx at gmail.com>
Date: Sun, 28 Jun 2026 22:27:23 +0300
Subject: [PATCH 1/4] [clang] Don't add comments to the AST if not requested
---
clang/include/clang/Lex/PreprocessorOptions.h | 5 ++++
clang/include/clang/Sema/Sema.h | 5 ++++
clang/lib/Frontend/ASTUnit.cpp | 6 ++++
clang/lib/Parse/Parser.cpp | 11 +++++--
clang/lib/Sema/Sema.cpp | 29 +++++++++++++++++++
5 files changed, 53 insertions(+), 3 deletions(-)
diff --git a/clang/include/clang/Lex/PreprocessorOptions.h b/clang/include/clang/Lex/PreprocessorOptions.h
index 4d1a30712836f..5d695e5f0e875 100644
--- a/clang/include/clang/Lex/PreprocessorOptions.h
+++ b/clang/include/clang/Lex/PreprocessorOptions.h
@@ -157,6 +157,11 @@ class PreprocessorOptions {
/// clients don't use them.
bool WriteCommentListToPCH = true;
+ /// Force the front end to retain all documentation comments in the AST, even
+ /// when no comment consuming diagnostic or language option is enabled. Tools
+ /// that query comments after parsing set this
+ bool RetainComments = false;
+
/// When enabled, preprocessor is in a mode for parsing a single file only.
///
/// Disables #includes of other files and if there are unresolved identifiers
diff --git a/clang/include/clang/Sema/Sema.h b/clang/include/clang/Sema/Sema.h
index 2cf16fac83282..b818f4c4c4a60 100644
--- a/clang/include/clang/Sema/Sema.h
+++ b/clang/include/clang/Sema/Sema.h
@@ -1130,6 +1130,11 @@ class Sema final : public SemaBase {
void ActOnComment(SourceRange Comment);
+ /// Returns true if a comment at \p Loc should be retained in the AST
+ /// (some consumer such as -Wdocumentation, -fparse-all-comments, code
+ /// completion, or AST-file serialization may read it back).
+ bool shouldRetainCommentsFromLexer(SourceLocation Loc) const;
+
/// Retrieve the parser's current scope.
///
/// This routine must only be used when it is certain that semantic analysis
diff --git a/clang/lib/Frontend/ASTUnit.cpp b/clang/lib/Frontend/ASTUnit.cpp
index 2974cf2660184..404761c4488f7 100644
--- a/clang/lib/Frontend/ASTUnit.cpp
+++ b/clang/lib/Frontend/ASTUnit.cpp
@@ -1533,6 +1533,9 @@ ASTUnit *ASTUnit::LoadFromCompilerInvocationAction(
// We'll manage file buffers ourselves.
CI->getPreprocessorOpts().RetainRemappedFileBuffers = true;
+ // libclang and other ASTUnit clients query documentation comments after
+ // parsing, so keep them in the AST.
+ CI->getPreprocessorOpts().RetainComments = true;
CI->getFrontendOpts().DisableFree = false;
ProcessWarningOptions(AST->getDiagnostics(), CI->getDiagnosticOpts(),
AST->getFileManager().getVirtualFileSystem());
@@ -1641,6 +1644,9 @@ bool ASTUnit::LoadFromCompilerInvocation(
// We'll manage file buffers ourselves.
Invocation->getPreprocessorOpts().RetainRemappedFileBuffers = true;
+ // libclang and other ASTUnit clients query documentation comments after
+ // parsing, so keep them in the AST.
+ Invocation->getPreprocessorOpts().RetainComments = true;
Invocation->getFrontendOpts().DisableFree = false;
getDiagnostics().Reset();
ProcessWarningOptions(getDiagnostics(), Invocation->getDiagnosticOpts(),
diff --git a/clang/lib/Parse/Parser.cpp b/clang/lib/Parse/Parser.cpp
index 5e1fd4df1a3f0..6b7c4bce6645c 100644
--- a/clang/lib/Parse/Parser.cpp
+++ b/clang/lib/Parse/Parser.cpp
@@ -74,8 +74,12 @@ Parser::Parser(Preprocessor &pp, Sema &actions, bool skipFunctionBodies)
// destructor.
initializePragmaHandlers();
- CommentSemaHandler.reset(new ActionCommentHandler(actions));
- PP.addCommentHandler(CommentSemaHandler.get());
+ // Only install the comment handler when some consumer may read documentation
+ // comments back.
+ if (actions.shouldRetainCommentsFromLexer(SourceLocation())) {
+ CommentSemaHandler.reset(new ActionCommentHandler(actions));
+ PP.addCommentHandler(CommentSemaHandler.get());
+ }
PP.setCodeCompletionHandler(*this);
@@ -481,7 +485,8 @@ Parser::~Parser() {
resetPragmaHandlers();
- PP.removeCommentHandler(CommentSemaHandler.get());
+ if (CommentSemaHandler)
+ PP.removeCommentHandler(CommentSemaHandler.get());
PP.clearCodeCompletionHandler();
diff --git a/clang/lib/Sema/Sema.cpp b/clang/lib/Sema/Sema.cpp
index 78fbc9e31842d..7a7329c271716 100644
--- a/clang/lib/Sema/Sema.cpp
+++ b/clang/lib/Sema/Sema.cpp
@@ -24,6 +24,7 @@
#include "clang/AST/StmtCXX.h"
#include "clang/AST/TypeOrdering.h"
#include "clang/Basic/DarwinSDKInfo.h"
+#include "clang/Basic/DiagnosticComment.h"
#include "clang/Basic/DiagnosticOptions.h"
#include "clang/Basic/PartialDiagnostic.h"
#include "clang/Basic/SourceManager.h"
@@ -31,6 +32,7 @@
#include "clang/Lex/HeaderSearch.h"
#include "clang/Lex/HeaderSearchOptions.h"
#include "clang/Lex/Preprocessor.h"
+#include "clang/Lex/PreprocessorOptions.h"
#include "clang/Sema/CXXFieldCollector.h"
#include "clang/Sema/EnterExpressionEvaluationContext.h"
#include "clang/Sema/ExternalSemaSource.h"
@@ -2704,10 +2706,37 @@ LambdaScopeInfo *Sema::getCurGenericLambda() {
}
+bool Sema::shouldRetainCommentsFromLexer(SourceLocation Loc) const {
+ if (LangOpts.CommentOpts.ParseAllComments)
+ return true;
+
+ if (PP.getPreprocessorOpts().RetainComments)
+ return true;
+
+ // When building a PCH the comments are serialized into the AST file
+ // so downstream consumers like clangd) can retrieve documentation, and the
+ // incremental/REPL front end may query them interactively.
+ if (TUKind != TU_Complete)
+ return true;
+
+ if (PP.isCodeCompletionEnabled())
+ return true;
+
+ // Keep the comment if -Wdocumentation is enabled at its location (checking
+ // the location handles warnings turned on by `#pragma clang diagnostic`).
+ if (!Diags.isIgnored(diag::warn_doc_param_not_found, Loc) ||
+ !Diags.isIgnored(diag::warn_unknown_comment_command_name, Loc))
+ return true;
+
+ return false;
+}
+
void Sema::ActOnComment(SourceRange Comment) {
if (!LangOpts.RetainCommentsFromSystemHeaders &&
SourceMgr.isInSystemHeader(Comment.getBegin()))
return;
+ if (!shouldRetainCommentsFromLexer(Comment.getBegin()))
+ return;
RawComment RC(SourceMgr, Comment, LangOpts.CommentOpts, false);
if (RC.isAlmostTrailingComment() || RC.hasUnsupportedSplice(SourceMgr)) {
SourceRange MagicMarkerRange(Comment.getBegin(),
>From 402fcc0771fc98940295fd1b4d55dfce8379f98b Mon Sep 17 00:00:00 2001
From: Anonmiraj <ezzibrahimx at gmail.com>
Date: Sun, 28 Jun 2026 22:41:05 +0300
Subject: [PATCH 2/4] fix formatting
---
clang/lib/Sema/Sema.cpp | 1 -
1 file changed, 1 deletion(-)
diff --git a/clang/lib/Sema/Sema.cpp b/clang/lib/Sema/Sema.cpp
index 7a7329c271716..b44a710907134 100644
--- a/clang/lib/Sema/Sema.cpp
+++ b/clang/lib/Sema/Sema.cpp
@@ -2705,7 +2705,6 @@ LambdaScopeInfo *Sema::getCurGenericLambda() {
return nullptr;
}
-
bool Sema::shouldRetainCommentsFromLexer(SourceLocation Loc) const {
if (LangOpts.CommentOpts.ParseAllComments)
return true;
>From 1c096366247cdf068126e3415443641bcbdd1c29 Mon Sep 17 00:00:00 2001
From: Anonmiraj <ezzibrahimx at gmail.com>
Date: Sun, 28 Jun 2026 23:38:28 +0300
Subject: [PATCH 3/4] retain comments with -fretain-comments so --doxygen works
---
clang-tools-extra/clang-doc/tool/ClangDocMain.cpp | 3 ++-
clang/include/clang/Options/Options.td | 6 ++++++
clang/lib/Driver/ToolChains/Clang.cpp | 2 ++
3 files changed, 10 insertions(+), 1 deletion(-)
diff --git a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
index 38002f5111a9f..e9c61e7a96d51 100644
--- a/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
+++ b/clang-tools-extra/clang-doc/tool/ClangDocMain.cpp
@@ -292,7 +292,8 @@ Example usage for a project using a compile commands database:
llvm::outs() << "Emiting docs in " << Format << " format.\n";
auto G = ExitOnErr(doc::findGeneratorByName(Format));
- ArgumentsAdjuster ArgAdjuster;
+ ArgumentsAdjuster ArgAdjuster = getInsertArgumentAdjuster(
+ "-fretain-comments", tooling::ArgumentInsertPosition::END);
if (!DoxygenOnly)
ArgAdjuster = combineAdjusters(
getInsertArgumentAdjuster("-fparse-all-comments",
diff --git a/clang/include/clang/Options/Options.td b/clang/include/clang/Options/Options.td
index 5d5d409ac5494..b102dca258e90 100644
--- a/clang/include/clang/Options/Options.td
+++ b/clang/include/clang/Options/Options.td
@@ -2119,6 +2119,12 @@ defm define_target_os_macros : OptInCC1FFlag<"define-target-os-macros",
def fparse_all_comments : Flag<["-"], "fparse-all-comments">, Group<f_clang_Group>,
Visibility<[ClangOption, CC1Option]>,
MarshallingInfoFlag<LangOpts<"CommentOpts.ParseAllComments">>;
+def fretain_comments : Flag<["-"], "fretain-comments">, Group<f_clang_Group>,
+ Visibility<[ClangOption, CC1Option]>,
+ HelpText<"Retain documentation comments in the AST even when no diagnostic or "
+ "language option would otherwise require them (e.g. for tools that "
+ "query comments after parsing)">,
+ MarshallingInfoFlag<PreprocessorOpts<"RetainComments">>;
def frecord_command_line : Flag<["-"], "frecord-command-line">,
DocBrief<[{Generate a section named ".GCC.command.line" containing the
driver command-line. After linking, the section may contain multiple command
diff --git a/clang/lib/Driver/ToolChains/Clang.cpp b/clang/lib/Driver/ToolChains/Clang.cpp
index a3a3954bc464e..de7b903e55022 100644
--- a/clang/lib/Driver/ToolChains/Clang.cpp
+++ b/clang/lib/Driver/ToolChains/Clang.cpp
@@ -8085,6 +8085,8 @@ void Clang::ConstructJob(Compilation &C, const JobAction &JA,
Args.AddAllArgs(CmdArgs, options::OPT_fcomment_block_commands);
// Forward -fparse-all-comments to -cc1.
Args.AddAllArgs(CmdArgs, options::OPT_fparse_all_comments);
+ // Forward -fretain-comments to -cc1.
+ Args.AddAllArgs(CmdArgs, options::OPT_fretain_comments);
// Turn -fplugin=name.so into -load name.so
for (const Arg *A : Args.filtered(options::OPT_fplugin_EQ)) {
>From d63eb920b68559d6a49fa49d4b9429367c8ce661 Mon Sep 17 00:00:00 2001
From: Anonmiraj <ezzibrahimx at gmail.com>
Date: Mon, 29 Jun 2026 09:40:32 +0300
Subject: [PATCH 4/4] fix ci
---
clang/lib/ExtractAPI/ExtractAPIConsumer.cpp | 3 +++
clang/lib/Frontend/FrontendActions.cpp | 6 ++++++
2 files changed, 9 insertions(+)
diff --git a/clang/lib/ExtractAPI/ExtractAPIConsumer.cpp b/clang/lib/ExtractAPI/ExtractAPIConsumer.cpp
index 85da480fb67a6..6c6076e889f5a 100644
--- a/clang/lib/ExtractAPI/ExtractAPIConsumer.cpp
+++ b/clang/lib/ExtractAPI/ExtractAPIConsumer.cpp
@@ -448,6 +448,9 @@ ExtractAPIAction::CreateASTConsumer(CompilerInstance &CI, StringRef InFile) {
}
bool ExtractAPIAction::PrepareToExecuteAction(CompilerInstance &CI) {
+ // ExtractAPI reads documentation comments off the AST
+ CI.getPreprocessorOpts().RetainComments = true;
+
auto &Inputs = CI.getFrontendOpts().Inputs;
if (Inputs.empty())
return true;
diff --git a/clang/lib/Frontend/FrontendActions.cpp b/clang/lib/Frontend/FrontendActions.cpp
index ba3487d52e380..4849934954098 100644
--- a/clang/lib/Frontend/FrontendActions.cpp
+++ b/clang/lib/Frontend/FrontendActions.cpp
@@ -103,6 +103,8 @@ ASTPrintAction::CreateASTConsumer(CompilerInstance &CI, StringRef InFile) {
std::unique_ptr<ASTConsumer>
ASTDumpAction::CreateASTConsumer(CompilerInstance &CI, StringRef InFile) {
+ // Dumping the AST shows documentation comments
+ CI.getPreprocessorOpts().RetainComments = true;
const FrontendOptions &Opts = CI.getFrontendOpts();
return CreateASTDumper(nullptr /*Dump to stdout.*/, Opts.ASTDumpFilter,
Opts.ASTDumpDecls, Opts.ASTDumpAll,
@@ -267,6 +269,10 @@ GenerateModuleFromModuleMapAction::CreateOutputFile(CompilerInstance &CI,
bool GenerateModuleInterfaceAction::PrepareToExecuteAction(
CompilerInstance &CI) {
+ // Documentation comments must still be serialized into the BMI
+ // so importers can query them
+ CI.getPreprocessorOpts().RetainComments = true;
+
for (const auto &FIF : CI.getFrontendOpts().Inputs) {
if (const auto InputFormat = FIF.getKind().getFormat();
InputFormat != InputKind::Format::Source) {
More information about the cfe-commits
mailing list