[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
Fri Nov 6 05:57:03 PST 2026


https://github.com/daandemeyer updated https://github.com/llvm/llvm-project/pull/237623

>From 2c94cac171b35bb2f353201ec34cc17e6cb338b1 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 84ee08b334c9fb..71319e457c45dc 100644
--- a/clang-tools-extra/clang-tidy/bugprone/ArgumentCommentCheck.cpp
+++ b/clang-tools-extra/clang-tidy/bugprone/ArgumentCommentCheck.cpp
@@ -36,6 +36,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)),
@@ -67,6 +68,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);
@@ -267,6 +269,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))
@@ -281,7 +301,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);
 
@@ -290,7 +311,7 @@ ArgumentCommentCheck::shouldAddComment(const Expr *Arg) const {
   Arg = Arg->IgnoreImplicit();
   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) ||
@@ -315,6 +336,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)
@@ -331,6 +353,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),
@@ -396,17 +424,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);
     }
   }
 }
@@ -419,6 +452,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);
@@ -429,7 +463,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 758d7f3725b035..85812002101ea4 100644
--- a/clang-tools-extra/clang-tidy/bugprone/ArgumentCommentCheck.h
+++ b/clang-tools-extra/clang-tidy/bugprone/ArgumentCommentCheck.h
@@ -47,6 +47,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;
@@ -63,10 +64,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 de205ae3343db9..7cb17049169532 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.
 
 - Improved {doc}`bugprone-assignment-in-if-condition
   <clang-tidy/checks/bugprone/assignment-in-if-condition>` check by ignoring
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 34dfc7029cbc43..d0bdfd6960ef9b 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 d6782dcf60f02645e5ab98df166c2b0cf184631f 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 71319e457c45dc..bc2a26d3c83a9f 100644
--- a/clang-tools-extra/clang-tidy/bugprone/ArgumentCommentCheck.cpp
+++ b/clang-tools-extra/clang-tidy/bugprone/ArgumentCommentCheck.cpp
@@ -53,6 +53,10 @@ ArgumentCommentCheck::ArgumentCommentCheck(StringRef Name,
           Options.get("CommentUserDefinedLiterals", false)),
       IgnoredParameterNames(utils::options::parseStringList(
           Options.get("IgnoredParameterNames", ""))),
+      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);
@@ -83,6 +87,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) {
@@ -302,7 +310,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);
 
@@ -311,8 +320,24 @@ ArgumentCommentCheck::shouldAddComment(const Expr *Arg,
   Arg = Arg->IgnoreImplicit();
   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) ||
@@ -392,9 +417,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());
     }
 
@@ -430,7 +457,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 85812002101ea4..c61b970d895a25 100644
--- a/clang-tools-extra/clang-tidy/bugprone/ArgumentCommentCheck.h
+++ b/clang-tools-extra/clang-tidy/bugprone/ArgumentCommentCheck.h
@@ -61,13 +61,15 @@ class ArgumentCommentCheck : public ClangTidyCheck {
   const unsigned CommentUserDefinedLiterals : 1;
   const std::vector<StringRef> IgnoredParameterNames;
   std::vector<llvm::Regex> IgnoredParameterNameRegexes;
+  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 7cb17049169532..a9c8ce90e27cc2 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.
 
 - Improved {doc}`bugprone-assignment-in-if-condition
   <clang-tidy/checks/bugprone/assignment-in-if-condition>` check by ignoring
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 d0bdfd6960ef9b..4337ed962c8aac 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:
@@ -162,8 +162,8 @@ foo(/*MeaningOfLife=*/42);
 
 ```{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:
@@ -289,3 +289,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