[clang-tools-extra] [clang-tidy] Make bugprone-argument-comment useful for C code (PR #237623)
Daan De Meyer via cfe-commits
cfe-commits at lists.llvm.org
Mon Nov 9 01:56:14 PST 2026
https://github.com/daandemeyer updated https://github.com/llvm/llvm-project/pull/237623
>From 148268fc1d0926807ad2cec18116c8d416e78c1c Mon Sep 17 00:00:00 2001
From: Daan De Meyer <daan at amutable.com>
Date: Fri, 30 Oct 2026 16:00:32 +0100
Subject: [PATCH 1/2] [clang-tidy] Check macro argument calls in
argument-comment
bugprone-argument-comment never adds a missing comment to an argument that
comes from a macro expansion. That also skips calls that the user wrote in
a macro argument, such as ASSERT(f(0)). Many C projects check the results
of their function calls that way.
Let's add an IgnoreMacros option. When it's false, we add the comment when
the argument and the closing parenthesis of the call map to one range of
the file, starting at the argument. That's the case when the user wrote
the call in a macro argument. A call in a macro body fails the test,
because a fix-it would edit the macro definition that every expansion
shares. An argument that is passed through another macro, such as
f(ID(0)), fails it too, because the fix-it would insert the comment inside
the argument of ID.
IgnoreMacros defaults to true, so existing configurations don't get new
warnings. The comparison of existing comments with parameter names already
runs for calls in macro arguments, so the option doesn't affect it.
Signed-off-by: Daan De Meyer <daan at amutable.com>
---
.../bugprone/ArgumentCommentCheck.cpp | 52 +++++++++++---
.../bugprone/ArgumentCommentCheck.h | 5 +-
clang-tools-extra/docs/ReleaseNotes.md | 2 +-
.../checks/bugprone/argument-comment.md | 8 +++
.../bugprone/argument-comment-macros.cpp | 72 +++++++++++++++++++
5 files changed, 127 insertions(+), 12 deletions(-)
create mode 100644 clang-tools-extra/test/clang-tidy/checkers/bugprone/argument-comment-macros.cpp
diff --git a/clang-tools-extra/clang-tidy/bugprone/ArgumentCommentCheck.cpp b/clang-tools-extra/clang-tidy/bugprone/ArgumentCommentCheck.cpp
index b53c501dd698bd..36d0bed323c18c 100644
--- a/clang-tools-extra/clang-tidy/bugprone/ArgumentCommentCheck.cpp
+++ b/clang-tools-extra/clang-tidy/bugprone/ArgumentCommentCheck.cpp
@@ -66,6 +66,7 @@ ArgumentCommentCheck::ArgumentCommentCheck(StringRef Name,
ClangTidyContext *Context)
: ClangTidyCheck(Name, Context),
StrictMode(Options.get("StrictMode", false)),
+ IgnoreMacros(Options.get("IgnoreMacros", true)),
IgnoreSingleArgument(Options.get("IgnoreSingleArgument", false)),
CommentAnonymousInitLists(
Options.get("CommentAnonymousInitLists", false)),
@@ -97,6 +98,7 @@ ArgumentCommentCheck::ArgumentCommentCheck(StringRef Name,
void ArgumentCommentCheck::storeOptions(ClangTidyOptions::OptionMap &Opts) {
Options.store(Opts, "StrictMode", StrictMode);
+ Options.store(Opts, "IgnoreMacros", IgnoreMacros);
Options.store(Opts, "IgnoreSingleArgument", IgnoreSingleArgument);
Options.store(Opts, "CommentAnonymousInitLists", CommentAnonymousInitLists);
Options.store(Opts, "CommentBoolLiterals", CommentBoolLiterals);
@@ -297,6 +299,24 @@ static InitListKind getInitListKind(const Expr *Arg) {
return InitListKind::None;
}
+// Returns the file location of Arg. Returns an invalid location when Arg and
+// the closing parenthesis of the call at CloseLoc don't map to one range of the
+// file that starts at Arg. That happens when a macro body contains Arg or the
+// closing parenthesis, or when Arg is in another macro argument than the
+// closing parenthesis, such as the `0` in `f(ID(0))`.
+static SourceLocation getWrittenArgLoc(const Expr *Arg, SourceLocation CloseLoc,
+ const SourceManager &SM,
+ const LangOptions &LangOpts) {
+ const CharSourceRange Range = Lexer::makeFileCharRange(
+ CharSourceRange::getTokenRange(Arg->getBeginLoc(), CloseLoc), SM,
+ LangOpts);
+ const SourceLocation ArgLoc =
+ SM.getExpansionLoc(SM.getTopMacroCallerLoc(Arg->getBeginLoc()));
+ if (Range.isInvalid() || Range.getBegin() != ArgLoc)
+ return {};
+ return ArgLoc;
+}
+
static bool isParenthesizedTemporary(const Expr *Arg) {
Arg = Arg->IgnoreUnlessSpelledInSource();
if (const auto *TempObject = dyn_cast<CXXTemporaryObjectExpr>(Arg))
@@ -311,7 +331,8 @@ static bool isParenthesizedTemporary(const Expr *Arg) {
// Given the argument type and the options determine if we should be adding an
// argument comment and which diagnostic wording to use.
ArgumentCommentCheck::CommentKind
-ArgumentCommentCheck::shouldAddComment(const Expr *Arg) const {
+ArgumentCommentCheck::shouldAddComment(const Expr *Arg,
+ const SourceManager &SM) const {
const InitListKind Kind = getInitListKind(Arg);
const bool IsParenthesizedTemporary = isParenthesizedTemporary(Arg);
@@ -324,7 +345,7 @@ ArgumentCommentCheck::shouldAddComment(const Expr *Arg) const {
const bool IsZero = IntegerLit && IntegerLit->getValue().isZero();
if (const auto *UO = dyn_cast<UnaryOperator>(Arg))
Arg = UO->getSubExpr()->IgnoreImplicit();
- if (Arg->getExprLoc().isMacroID())
+ if (SM.getTopMacroCallerLoc(Arg->getExprLoc()).isMacroID())
return CommentKind::None;
if ((CommentAnonymousInitLists && Kind == InitListKind::Anonymous) ||
@@ -352,6 +373,7 @@ ArgumentCommentCheck::shouldAddComment(const Expr *Arg) const {
void ArgumentCommentCheck::checkCallArgs(ASTContext *Ctx,
const FunctionDecl *OriginalCallee,
SourceLocation ArgBeginLoc,
+ SourceLocation CloseLoc,
llvm::ArrayRef<const Expr *> Args) {
const FunctionDecl *Callee = resolveMocks(OriginalCallee);
if (!Callee)
@@ -368,6 +390,12 @@ void ArgumentCommentCheck::checkCallArgs(ASTContext *Ctx,
if ((NumArgs == 0) || (IgnoreSingleArgument && NumArgs == 1))
return;
+ const SourceManager &SM = Ctx->getSourceManager();
+ // A call whose closing parenthesis is a macro location is in a macro
+ // argument, such as `f(0)` in `ASSERT(f(0))`. getWrittenArgLoc() rejects
+ // calls in a macro body.
+ const bool AddMissingComments = !IgnoreMacros || CloseLoc.isFileID();
+
const auto MakeFileCharRange = [Ctx](SourceLocation Begin,
SourceLocation End) {
return Lexer::makeFileCharRange(CharSourceRange::getCharRange(Begin, End),
@@ -433,17 +461,22 @@ void ArgumentCommentCheck::checkCallArgs(ASTContext *Ctx,
// If the argument comments are missing for configured argument kinds, add
// them.
- const CommentKind Kind = shouldAddComment(Args[I]);
- if (Comments.empty() && Kind != CommentKind::None) {
+ if (!AddMissingComments || !Comments.empty())
+ continue;
+ const SourceLocation ArgLoc =
+ getWrittenArgLoc(Args[I], CloseLoc, SM, Ctx->getLangOpts());
+ if (ArgLoc.isInvalid())
+ continue;
+ const CommentKind Kind = shouldAddComment(Args[I], SM);
+ if (Kind != CommentKind::None) {
SmallString<32> ArgComment;
llvm::Twine(llvm::Twine("/*") + II->getName() + "=*/")
.toStringRef(ArgComment);
const DiagnosticBuilder Diag =
- diag(Args[I]->getBeginLoc(),
- "argument comment missing for %select{literal argument|"
- "argument}0 %1")
+ diag(ArgLoc, "argument comment missing for %select{literal argument|"
+ "argument}0 %1")
<< (Kind == CommentKind::Literal ? 0 : 1) << II
- << FixItHint::CreateInsertion(Args[I]->getBeginLoc(), ArgComment);
+ << FixItHint::CreateInsertion(ArgLoc, ArgComment);
}
}
}
@@ -456,6 +489,7 @@ void ArgumentCommentCheck::check(const MatchFinder::MatchResult &Result) {
return;
checkCallArgs(Result.Context, Callee, Call->getCallee()->getEndLoc(),
+ Call->getEndLoc(),
llvm::ArrayRef(Call->getArgs(), Call->getNumArgs()));
} else {
const auto *Construct = cast<CXXConstructExpr>(E);
@@ -466,7 +500,7 @@ void ArgumentCommentCheck::check(const MatchFinder::MatchResult &Result) {
}
checkCallArgs(
Result.Context, Construct->getConstructor(),
- Construct->getParenOrBraceRange().getBegin(),
+ Construct->getParenOrBraceRange().getBegin(), Construct->getEndLoc(),
llvm::ArrayRef(Construct->getArgs(), Construct->getNumArgs()));
}
}
diff --git a/clang-tools-extra/clang-tidy/bugprone/ArgumentCommentCheck.h b/clang-tools-extra/clang-tidy/bugprone/ArgumentCommentCheck.h
index c24734893e01db..47fd0ea7b4eddf 100644
--- a/clang-tools-extra/clang-tidy/bugprone/ArgumentCommentCheck.h
+++ b/clang-tools-extra/clang-tidy/bugprone/ArgumentCommentCheck.h
@@ -49,6 +49,7 @@ class ArgumentCommentCheck : public ClangTidyCheck {
};
const unsigned StrictMode : 1;
+ const unsigned IgnoreMacros : 1;
const unsigned IgnoreSingleArgument : 1;
const unsigned CommentAnonymousInitLists : 1;
const unsigned CommentBoolLiterals : 1;
@@ -65,10 +66,10 @@ class ArgumentCommentCheck : public ClangTidyCheck {
llvm::Regex IdentRE;
void checkCallArgs(ASTContext *Ctx, const FunctionDecl *Callee,
- SourceLocation ArgBeginLoc,
+ SourceLocation ArgBeginLoc, SourceLocation CloseLoc,
llvm::ArrayRef<const Expr *> Args);
- CommentKind shouldAddComment(const Expr *Arg) const;
+ CommentKind shouldAddComment(const Expr *Arg, const SourceManager &SM) const;
};
} // namespace clang::tidy::bugprone
diff --git a/clang-tools-extra/docs/ReleaseNotes.md b/clang-tools-extra/docs/ReleaseNotes.md
index 4cd6b4b8a82eee..dedf0e712e6636 100644
--- a/clang-tools-extra/docs/ReleaseNotes.md
+++ b/clang-tools-extra/docs/ReleaseNotes.md
@@ -186,7 +186,7 @@ infrastructure are described first, followed by tool-specific sections.
- Improved {doc}`bugprone-argument-comment
<clang-tidy/checks/bugprone/argument-comment>` check by adding the
- {option}`IgnoredParameterNames` option to skip parameters by name.
+ {option}`IgnoreMacros` and {option}`IgnoredParameterNames` options.
The `ZeroOnly` value of {option}`CommentIntegerLiterals` adds comments only to
integer literals with the value zero. The option still accepts `true` and
`false`.
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/argument-comment.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/argument-comment.md
index 2b5e11a9694c28..130e95602732cc 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/argument-comment.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/argument-comment.md
@@ -29,6 +29,14 @@ underscores and case when comparing names -- otherwise they are taken into
account. Default is `false`.
```
+```{option} IgnoreMacros
+When `false`, the check also adds missing comments to calls in a macro
+argument, such as `ASSERT(f(0))`. It never adds them to calls in a macro body,
+or to arguments that you pass through another macro, such as `f(ID(0))`. The
+check compares argument comments with parameter names regardless of this
+option. Default is `true`.
+```
+
```{option} IgnoreSingleArgument
When `true`, the check will ignore the single argument. Default is `false`.
```
diff --git a/clang-tools-extra/test/clang-tidy/checkers/bugprone/argument-comment-macros.cpp b/clang-tools-extra/test/clang-tidy/checkers/bugprone/argument-comment-macros.cpp
new file mode 100644
index 00000000000000..f93162fa360ff0
--- /dev/null
+++ b/clang-tools-extra/test/clang-tidy/checkers/bugprone/argument-comment-macros.cpp
@@ -0,0 +1,72 @@
+// RUN: %check_clang_tidy -check-suffixes=,MACROS %s bugprone-argument-comment %t -- \
+// RUN: -config="{CheckOptions: { \
+// RUN: bugprone-argument-comment.CommentBoolLiterals: true, \
+// RUN: bugprone-argument-comment.CommentIntegerLiterals: true, \
+// RUN: bugprone-argument-comment.IgnoreMacros: false}}" --
+// RUN: %check_clang_tidy %s bugprone-argument-comment %t -- \
+// RUN: -config="{CheckOptions: { \
+// RUN: bugprone-argument-comment.CommentBoolLiterals: true, \
+// RUN: bugprone-argument-comment.CommentIntegerLiterals: true}}" --
+
+struct A {
+ void foo(bool abc);
+};
+
+void g(int a);
+void j(int a, int b, int c);
+void k(int a, int b);
+void real_g(int a, bool b);
+
+#define CHECK(e) do { (void)(e); } while (0)
+#define CHECK_TWICE(e) do { (void)(e); (void)(e); } while (0)
+#define ID(x) x
+#define X(x) (x)
+#define VOID(e) ((void)(e))
+#define CALL_G(x) g(x)
+#define CALL_G_1 g(1)
+#define CALL(fn, a) fn(a)
+#define CALL2(fn, a) fn(a, a)
+#define my_g real_g
+
+void test() {
+ A a;
+
+ my_g(0, true);
+ // CHECK-MESSAGES: [[@LINE-1]]:8: warning: argument comment missing for literal argument 'a' [bugprone-argument-comment]
+ // CHECK-MESSAGES: [[@LINE-2]]:11: warning: argument comment missing for literal argument 'b' [bugprone-argument-comment]
+ // CHECK-FIXES: my_g(/*a=*/0, /*b=*/true);
+
+ ID(real_g)(0, true);
+ // CHECK-MESSAGES: [[@LINE-1]]:14: warning: argument comment missing for literal argument 'a' [bugprone-argument-comment]
+ // CHECK-MESSAGES: [[@LINE-2]]:17: warning: argument comment missing for literal argument 'b' [bugprone-argument-comment]
+ // CHECK-FIXES: ID(real_g)(/*a=*/0, /*b=*/true);
+
+ CHECK(a.foo(true));
+ // CHECK-MESSAGES-MACROS: [[@LINE-1]]:15: warning: argument comment missing for literal argument 'abc' [bugprone-argument-comment]
+ // CHECK-FIXES-MACROS: CHECK(a.foo(/*abc=*/true));
+ CHECK(a.foo(/*abc=*/true));
+
+ CHECK(j(1, X(1), -1));
+ // CHECK-MESSAGES-MACROS: [[@LINE-1]]:11: warning: argument comment missing for literal argument 'a' [bugprone-argument-comment]
+ // CHECK-MESSAGES-MACROS: [[@LINE-2]]:20: warning: argument comment missing for literal argument 'c' [bugprone-argument-comment]
+ // CHECK-FIXES-MACROS: CHECK(j(/*a=*/1, X(1), /*c=*/-1));
+
+ CHECK_TWICE(g(1));
+ // CHECK-MESSAGES-MACROS: [[@LINE-1]]:17: warning: argument comment missing for literal argument 'a' [bugprone-argument-comment]
+ // CHECK-FIXES-MACROS: CHECK_TWICE(g(/*a=*/1));
+
+ CHECK(VOID(g(1)));
+ // CHECK-MESSAGES-MACROS: [[@LINE-1]]:16: warning: argument comment missing for literal argument 'a' [bugprone-argument-comment]
+ // CHECK-FIXES-MACROS: CHECK(VOID(g(/*a=*/1)));
+
+ // The check adds no comment when the literal and the closing parenthesis of
+ // the call are in different macro arguments, or when the call is in a macro
+ // body.
+ g(ID(1));
+ CHECK(g(ID(1)));
+ ID(g)(ID(1));
+ CALL_G(1);
+ CALL_G_1;
+ CALL(g, 1);
+ CALL2(k, 1);
+}
>From 6c3c32605a0c656aaa7aeaed8aeba848613e62cc Mon Sep 17 00:00:00 2001
From: Daan De Meyer <daan at amutable.com>
Date: Fri, 30 Oct 2026 16:02:51 +0100
Subject: [PATCH 2/2] [clang-tidy] Support NULL/true/false in argument-comment
Before C23, C has no nullptr, true and false keywords. C code spells them
with the NULL macro of <stddef.h> and the true and false macros of
<stdbool.h> instead. bugprone-argument-comment skips literals that come
from a macro, so CommentNullPtrs and CommentBoolLiterals don't apply to C
code that uses the macros. The same holds for C++: NULL is a macro there
too, and GNU C++98 defines true and false as macros in <stdbool.h>.
Let's treat an argument that is one of the macros in the new NullPtrMacros
and BoolLiteralMacros options like the literal it stands for. The check
already strips one unary operator before it classifies an argument, so -1
counts as an integer literal. The same holds for the macros, so !true
counts as true. The options default to NULL and to true and false. Other
macros already name their value, so they don't need a comment by default.
A project can add its own macros to the options, such as TRUE and FALSE.
The comment before an argument that follows a multi-token macro such as
NULL wasn't found either. In f(NULL, /*b=*/NULL), the range from the end
of the first NULL has no file range, and neither has the range of the
second argument. Let's fall back to an empty range at the start of the
argument, which maps to the location of the macro name. With that range,
the check also reports comments there that don't match the parameter
name.
Signed-off-by: Daan De Meyer <daan at amutable.com>
---
.../bugprone/ArgumentCommentCheck.cpp | 37 +++++++++--
.../bugprone/ArgumentCommentCheck.h | 4 +-
clang-tools-extra/docs/ReleaseNotes.md | 3 +-
.../checks/bugprone/argument-comment.md | 24 +++++--
.../checkers/bugprone/argument-comment-c.c | 64 +++++++++++++++++++
.../bugprone/argument-comment-gnu98.cpp | 18 ++++++
.../bugprone/argument-comment-macro-names.c | 46 +++++++++++++
7 files changed, 185 insertions(+), 11 deletions(-)
create mode 100644 clang-tools-extra/test/clang-tidy/checkers/bugprone/argument-comment-c.c
create mode 100644 clang-tools-extra/test/clang-tidy/checkers/bugprone/argument-comment-gnu98.cpp
create mode 100644 clang-tools-extra/test/clang-tidy/checkers/bugprone/argument-comment-macro-names.c
diff --git a/clang-tools-extra/clang-tidy/bugprone/ArgumentCommentCheck.cpp b/clang-tools-extra/clang-tidy/bugprone/ArgumentCommentCheck.cpp
index 36d0bed323c18c..eb8ca3780d676e 100644
--- a/clang-tools-extra/clang-tidy/bugprone/ArgumentCommentCheck.cpp
+++ b/clang-tools-extra/clang-tidy/bugprone/ArgumentCommentCheck.cpp
@@ -83,6 +83,10 @@ ArgumentCommentCheck::ArgumentCommentCheck(StringRef Name,
IgnoredParameterNames(utils::options::parseStringList(
Options.get("IgnoredParameterNames", ""))),
CommentIntegerLiterals(getCommentIntegerLiterals(Options)),
+ NullPtrMacros(utils::options::parseStringList(
+ Options.get("NullPtrMacros", "NULL"))),
+ BoolLiteralMacros(utils::options::parseStringList(
+ Options.get("BoolLiteralMacros", "true;false"))),
IdentRE("^(/\\* *)([_A-Za-z][_A-Za-z0-9]*)( *= *\\*/)$") {
for (const StringRef Name : IgnoredParameterNames) {
llvm::Regex Regex(Name);
@@ -113,6 +117,10 @@ void ArgumentCommentCheck::storeOptions(ClangTidyOptions::OptionMap &Opts) {
Options.store(Opts, "CommentUserDefinedLiterals", CommentUserDefinedLiterals);
Options.store(Opts, "IgnoredParameterNames",
utils::options::serializeStringList(IgnoredParameterNames));
+ Options.store(Opts, "NullPtrMacros",
+ utils::options::serializeStringList(NullPtrMacros));
+ Options.store(Opts, "BoolLiteralMacros",
+ utils::options::serializeStringList(BoolLiteralMacros));
}
void ArgumentCommentCheck::registerMatchers(MatchFinder *Finder) {
@@ -332,7 +340,8 @@ static bool isParenthesizedTemporary(const Expr *Arg) {
// argument comment and which diagnostic wording to use.
ArgumentCommentCheck::CommentKind
ArgumentCommentCheck::shouldAddComment(const Expr *Arg,
- const SourceManager &SM) const {
+ const ASTContext &Ctx) const {
+ const SourceManager &SM = Ctx.getSourceManager();
const InitListKind Kind = getInitListKind(Arg);
const bool IsParenthesizedTemporary = isParenthesizedTemporary(Arg);
@@ -345,8 +354,24 @@ ArgumentCommentCheck::shouldAddComment(const Expr *Arg,
const bool IsZero = IntegerLit && IntegerLit->getValue().isZero();
if (const auto *UO = dyn_cast<UnaryOperator>(Arg))
Arg = UO->getSubExpr()->IgnoreImplicit();
- if (SM.getTopMacroCallerLoc(Arg->getExprLoc()).isMacroID())
+
+ // C spells the null pointer constant with the macro `NULL`, and the boolean
+ // constants before C23 with the macros `true` and `false`. The options
+ // NullPtrMacros and BoolLiteralMacros contain `NULL`, `true` and `false` by
+ // default. Other macros, such as `MAX_SIZE`, already name their value and
+ // need no comment.
+ if (SM.getTopMacroCallerLoc(Arg->getExprLoc()).isMacroID()) {
+ const StringRef MacroName =
+ Lexer::getSourceText(CharSourceRange::getTokenRange(
+ SM.getTopMacroCallerLoc(Arg->getBeginLoc()),
+ SM.getTopMacroCallerLoc(Arg->getEndLoc())),
+ SM, Ctx.getLangOpts());
+ if ((CommentNullPtrs && llvm::is_contained(NullPtrMacros, MacroName)) ||
+ (CommentBoolLiterals &&
+ llvm::is_contained(BoolLiteralMacros, MacroName)))
+ return CommentKind::Literal;
return CommentKind::None;
+ }
if ((CommentAnonymousInitLists && Kind == InitListKind::Anonymous) ||
(CommentTypedInitLists && Kind == InitListKind::Typed) ||
@@ -429,9 +454,11 @@ void ArgumentCommentCheck::checkCallArgs(ASTContext *Ctx,
Comments = utils::lexer::getTrailingCommentsInRange(
BeforeArgument, Ctx->getSourceManager(), Ctx->getLangOpts());
} else {
- // Fall back to parsing back from the start of the argument.
+ // Fall back to parsing back from the start of the argument. The range
+ // is empty because a range that ends inside a macro expansion, such as
+ // the `)` of `NULL`, has no file range.
const CharSourceRange ArgsRange =
- MakeFileCharRange(Args[I]->getBeginLoc(), Args[I]->getEndLoc());
+ MakeFileCharRange(Args[I]->getBeginLoc(), Args[I]->getBeginLoc());
Comments = getCommentsBeforeLoc(Ctx, ArgsRange.getBegin());
}
@@ -467,7 +494,7 @@ void ArgumentCommentCheck::checkCallArgs(ASTContext *Ctx,
getWrittenArgLoc(Args[I], CloseLoc, SM, Ctx->getLangOpts());
if (ArgLoc.isInvalid())
continue;
- const CommentKind Kind = shouldAddComment(Args[I], SM);
+ const CommentKind Kind = shouldAddComment(Args[I], *Ctx);
if (Kind != CommentKind::None) {
SmallString<32> ArgComment;
llvm::Twine(llvm::Twine("/*") + II->getName() + "=*/")
diff --git a/clang-tools-extra/clang-tidy/bugprone/ArgumentCommentCheck.h b/clang-tools-extra/clang-tidy/bugprone/ArgumentCommentCheck.h
index 47fd0ea7b4eddf..c0bf450c5c5fe8 100644
--- a/clang-tools-extra/clang-tidy/bugprone/ArgumentCommentCheck.h
+++ b/clang-tools-extra/clang-tidy/bugprone/ArgumentCommentCheck.h
@@ -63,13 +63,15 @@ class ArgumentCommentCheck : public ClangTidyCheck {
const std::vector<StringRef> IgnoredParameterNames;
std::vector<llvm::Regex> IgnoredParameterNameRegexes;
const IntegerLiteralKind CommentIntegerLiterals;
+ const std::vector<StringRef> NullPtrMacros;
+ const std::vector<StringRef> BoolLiteralMacros;
llvm::Regex IdentRE;
void checkCallArgs(ASTContext *Ctx, const FunctionDecl *Callee,
SourceLocation ArgBeginLoc, SourceLocation CloseLoc,
llvm::ArrayRef<const Expr *> Args);
- CommentKind shouldAddComment(const Expr *Arg, const SourceManager &SM) const;
+ CommentKind shouldAddComment(const Expr *Arg, const ASTContext &Ctx) const;
};
} // namespace clang::tidy::bugprone
diff --git a/clang-tools-extra/docs/ReleaseNotes.md b/clang-tools-extra/docs/ReleaseNotes.md
index dedf0e712e6636..0456da1be23dff 100644
--- a/clang-tools-extra/docs/ReleaseNotes.md
+++ b/clang-tools-extra/docs/ReleaseNotes.md
@@ -186,7 +186,8 @@ infrastructure are described first, followed by tool-specific sections.
- Improved {doc}`bugprone-argument-comment
<clang-tidy/checks/bugprone/argument-comment>` check by adding the
- {option}`IgnoreMacros` and {option}`IgnoredParameterNames` options.
+ {option}`IgnoreMacros`, {option}`IgnoredParameterNames`,
+ {option}`NullPtrMacros` and {option}`BoolLiteralMacros` options.
The `ZeroOnly` value of {option}`CommentIntegerLiterals` adds comments only to
integer literals with the value zero. The option still accepts `true` and
`false`.
diff --git a/clang-tools-extra/docs/clang-tidy/checks/bugprone/argument-comment.md b/clang-tools-extra/docs/clang-tidy/checks/bugprone/argument-comment.md
index 130e95602732cc..d4e793167e1b28 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/bugprone/argument-comment.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/bugprone/argument-comment.md
@@ -74,8 +74,8 @@ foo(/*Dims=*/{});
```{option} CommentBoolLiterals
When `true`, the check will add argument comments in the format
-`/*ParameterName=*/` right before the boolean literal argument.
-Default is `false`.
+`/*ParameterName=*/` right before the boolean literal argument and the macros
+in {option}`BoolLiteralMacros`. Default is `false`.
```
Before:
@@ -183,8 +183,8 @@ open_file(Path, 1);
```{option} CommentNullPtrs
When `true`, the check will add argument comments in the format
-`/*ParameterName=*/` right before the nullptr literal argument.
-Default is `false`.
+`/*ParameterName=*/` right before the nullptr literal argument and the macros
+in {option}`NullPtrMacros`. Default is `false`.
```
Before:
@@ -310,3 +310,19 @@ double operator"" _km(long double);
foo(/*Distance=*/402.0_km);
```
+
+```{option} NullPtrMacros
+A semicolon-separated list of macros that {option}`CommentNullPtrs` treats like
+`nullptr`. An argument matches when it is one of these macros, with or without
+a unary operator in front of it. A macro that expands to one of these macros,
+such as `#define MY_NULL NULL`, doesn't match. Default is `NULL`.
+```
+
+```{option} BoolLiteralMacros
+A semicolon-separated list of macros that {option}`CommentBoolLiterals` treats
+like boolean literals. An argument matches when it is one of these macros, with
+or without a unary operator in front of it, such as `!true`. A macro that
+expands to one of these macros, such as `#define MY_TRUE true`, doesn't match.
+Default is `true;false`, which covers `<stdbool.h>` in C before C23 and in GNU
+C++98.
+```
diff --git a/clang-tools-extra/test/clang-tidy/checkers/bugprone/argument-comment-c.c b/clang-tools-extra/test/clang-tidy/checkers/bugprone/argument-comment-c.c
new file mode 100644
index 00000000000000..3d05b6c06c3fd4
--- /dev/null
+++ b/clang-tools-extra/test/clang-tidy/checkers/bugprone/argument-comment-c.c
@@ -0,0 +1,64 @@
+// RUN: %check_clang_tidy %s bugprone-argument-comment %t -- \
+// RUN: -config="{CheckOptions: { \
+// RUN: bugprone-argument-comment.CommentBoolLiterals: true, \
+// RUN: bugprone-argument-comment.CommentNullPtrs: true, \
+// RUN: bugprone-argument-comment.IgnoreMacros: false}}" --
+
+#include <stdbool.h>
+#include <stddef.h>
+
+#define CHECK(e) do { (void)(e); } while (0)
+#define ID(x) x
+#define MY_NULL NULL
+#define MY_TRUE true
+#define CALL_F f(NULL, true)
+
+int f(const char *path, bool force);
+int h(const char *path, const char *root);
+
+void test(void) {
+ f(NULL, false);
+ // CHECK-MESSAGES: [[@LINE-1]]:5: warning: argument comment missing for literal argument 'path' [bugprone-argument-comment]
+ // CHECK-MESSAGES: [[@LINE-2]]:11: warning: argument comment missing for literal argument 'force' [bugprone-argument-comment]
+ // CHECK-FIXES: f(/*path=*/NULL, /*force=*/false);
+ f(/*path=*/NULL, /*force=*/false);
+ f(/* path= */ NULL, /* force= */ true);
+
+ CHECK(f(NULL, true));
+ // CHECK-MESSAGES: [[@LINE-1]]:11: warning: argument comment missing for literal argument 'path' [bugprone-argument-comment]
+ // CHECK-MESSAGES: [[@LINE-2]]:17: warning: argument comment missing for literal argument 'force' [bugprone-argument-comment]
+ // CHECK-FIXES: CHECK(f(/*path=*/NULL, /*force=*/true));
+ CHECK(f(/*path=*/NULL, /*force=*/true));
+
+ h(NULL, NULL);
+ // CHECK-MESSAGES: [[@LINE-1]]:5: warning: argument comment missing for literal argument 'path' [bugprone-argument-comment]
+ // CHECK-MESSAGES: [[@LINE-2]]:11: warning: argument comment missing for literal argument 'root' [bugprone-argument-comment]
+ // CHECK-FIXES: h(/*path=*/NULL, /*root=*/NULL);
+ h(/*path=*/NULL, /*root=*/NULL);
+ CHECK(h(/* path= */ NULL, /* root= */ NULL));
+
+ h(NULL, /*rot=*/NULL);
+ // CHECK-MESSAGES: [[@LINE-1]]:5: warning: argument comment missing for literal argument 'path' [bugprone-argument-comment]
+ // CHECK-MESSAGES: [[@LINE-2]]:11: warning: argument name 'rot' in comment does not match parameter name 'root' [bugprone-argument-comment]
+ // CHECK-MESSAGES: :[[@LINE-26]]:37: note: 'root' declared here
+ // CHECK-FIXES: h(/*path=*/NULL, /*root=*/NULL);
+
+ f(/*path=*/NULL, !true);
+ // CHECK-MESSAGES: [[@LINE-1]]:20: warning: argument comment missing for literal argument 'force' [bugprone-argument-comment]
+ // CHECK-FIXES: f(/*path=*/NULL, /*force=*/!true);
+
+ f(/*path=*/NULL, ~true);
+ // CHECK-MESSAGES: [[@LINE-1]]:20: warning: argument comment missing for literal argument 'force' [bugprone-argument-comment]
+ // CHECK-FIXES: f(/*path=*/NULL, /*force=*/~true);
+
+ f(/*path=*/NULL, -false);
+ // CHECK-MESSAGES: [[@LINE-1]]:20: warning: argument comment missing for literal argument 'force' [bugprone-argument-comment]
+ // CHECK-FIXES: f(/*path=*/NULL, /*force=*/-false);
+
+ // The check adds no comment to other macros, to integers, to macros in
+ // another macro argument, and to calls in a macro body.
+ f(MY_NULL, MY_TRUE);
+ f(0, 1);
+ f(ID(NULL), ID(true));
+ CALL_F;
+}
diff --git a/clang-tools-extra/test/clang-tidy/checkers/bugprone/argument-comment-gnu98.cpp b/clang-tools-extra/test/clang-tidy/checkers/bugprone/argument-comment-gnu98.cpp
new file mode 100644
index 00000000000000..abb6e150e9d81d
--- /dev/null
+++ b/clang-tools-extra/test/clang-tidy/checkers/bugprone/argument-comment-gnu98.cpp
@@ -0,0 +1,18 @@
+// RUN: %check_clang_tidy -std=gnu++98 %s bugprone-argument-comment %t -- \
+// RUN: -config="{CheckOptions: { \
+// RUN: bugprone-argument-comment.CommentBoolLiterals: true, \
+// RUN: bugprone-argument-comment.CommentNullPtrs: true}}" --
+
+// In GNU C++98, <stdbool.h> defines `true` and `false` as macros, and
+// <stddef.h> defines `NULL` as `__null`.
+#include <stdbool.h>
+#include <stddef.h>
+
+void f(const char *path, bool force);
+
+void test() {
+ f(NULL, true);
+ // CHECK-MESSAGES: [[@LINE-1]]:5: warning: argument comment missing for literal argument 'path' [bugprone-argument-comment]
+ // CHECK-MESSAGES: [[@LINE-2]]:11: warning: argument comment missing for literal argument 'force' [bugprone-argument-comment]
+ // CHECK-FIXES: f(/*path=*/NULL, /*force=*/true);
+}
diff --git a/clang-tools-extra/test/clang-tidy/checkers/bugprone/argument-comment-macro-names.c b/clang-tools-extra/test/clang-tidy/checkers/bugprone/argument-comment-macro-names.c
new file mode 100644
index 00000000000000..4e4ca40b42d362
--- /dev/null
+++ b/clang-tools-extra/test/clang-tidy/checkers/bugprone/argument-comment-macro-names.c
@@ -0,0 +1,46 @@
+// RUN: %check_clang_tidy %s bugprone-argument-comment %t -- \
+// RUN: -config="{CheckOptions: { \
+// RUN: bugprone-argument-comment.CommentBoolLiterals: true, \
+// RUN: bugprone-argument-comment.CommentNullPtrs: true, \
+// RUN: bugprone-argument-comment.NullPtrMacros: 'NULL;MY_NULL', \
+// RUN: bugprone-argument-comment.BoolLiteralMacros: 'TRUE;FALSE'}}" --
+
+#include <stddef.h>
+
+#define MY_NULL ((void *)0)
+#define TRUE (1 == 1)
+#define FALSE 0
+#define OTHER 0
+
+int f(const char *path, int force);
+
+void test(void) {
+ // The check must add comments for the configured NULL, MY_NULL, TRUE and
+ // FALSE macros, including boolean macros with one unary operator. OTHER
+ // must remain unchanged because it is not configured.
+ f(MY_NULL, TRUE);
+ // CHECK-MESSAGES: [[@LINE-1]]:5: warning: argument comment missing for literal argument 'path' [bugprone-argument-comment]
+ // CHECK-MESSAGES: [[@LINE-2]]:14: warning: argument comment missing for literal argument 'force' [bugprone-argument-comment]
+ // CHECK-FIXES: f(/*path=*/MY_NULL, /*force=*/TRUE);
+
+ f(NULL, FALSE);
+ // CHECK-MESSAGES: [[@LINE-1]]:5: warning: argument comment missing for literal argument 'path' [bugprone-argument-comment]
+ // CHECK-MESSAGES: [[@LINE-2]]:11: warning: argument comment missing for literal argument 'force' [bugprone-argument-comment]
+ // CHECK-FIXES: f(/*path=*/NULL, /*force=*/FALSE);
+
+ f(NULL, OTHER);
+ // CHECK-MESSAGES: [[@LINE-1]]:5: warning: argument comment missing for literal argument 'path' [bugprone-argument-comment]
+ // CHECK-FIXES: f(/*path=*/NULL, OTHER);
+
+ f(/*path=*/NULL, !TRUE);
+ // CHECK-MESSAGES: [[@LINE-1]]:20: warning: argument comment missing for literal argument 'force' [bugprone-argument-comment]
+ // CHECK-FIXES: f(/*path=*/NULL, /*force=*/!TRUE);
+
+ f(/*path=*/NULL, ~TRUE);
+ // CHECK-MESSAGES: [[@LINE-1]]:20: warning: argument comment missing for literal argument 'force' [bugprone-argument-comment]
+ // CHECK-FIXES: f(/*path=*/NULL, /*force=*/~TRUE);
+
+ f(/*path=*/NULL, -FALSE);
+ // CHECK-MESSAGES: [[@LINE-1]]:20: warning: argument comment missing for literal argument 'force' [bugprone-argument-comment]
+ // CHECK-FIXES: f(/*path=*/NULL, /*force=*/-FALSE);
+}
More information about the cfe-commits
mailing list