[clang] [clang] Fix false positive with -Wdocumentation and explicit instanti… (PR #178223)

[Carlos Galvez via cfe-commits]

https://github.com/carlosgalvezp updated https://github.com/llvm/llvm-project/pull/178223

>From c3901a6e4f1e1451d86249485d517f232b108a09 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Carlos=20G=C3=A1lvez?= <carlos.galvez at zenseact.com>
Date: Mon, 26 Jan 2026 15:21:28 +0000
Subject: [PATCH] [clang] Fix false positive with -Wdocumentation and explicit
 instantiations

Solves a use case listed in #64087.
---
 clang/docs/ReleaseNotes.rst            |  3 +++
 clang/include/clang/AST/CommentSema.h  |  1 +
 clang/lib/AST/CommentSema.cpp          | 19 +++++++++++++++++++
 clang/test/Sema/warn-documentation.cpp | 10 ++++++++++
 4 files changed, 33 insertions(+)

diff --git a/clang/docs/ReleaseNotes.rst b/clang/docs/ReleaseNotes.rst
index 4bea29f4c1eb6..3dac89bdb8c37 100644
--- a/clang/docs/ReleaseNotes.rst
+++ b/clang/docs/ReleaseNotes.rst
@@ -281,6 +281,9 @@ Attribute Changes in Clang
 
 Improvements to Clang's diagnostics
 -----------------------------------
+- Fixed bug in ``-Wdocumentation`` so that it correctly handles explicit
+  function template instantiations (#64087).
+
 - ``-Wunused-but-set-variable`` now diagnoses file-scope variables with
   internal linkage (``static`` storage class) that are assigned but never used.
   This new coverage is added under the subgroup ``-Wunused-but-set-global``,
diff --git a/clang/include/clang/AST/CommentSema.h b/clang/include/clang/AST/CommentSema.h
index 3169e2b0d86b9..8dc6e50763dc5 100644
--- a/clang/include/clang/AST/CommentSema.h
+++ b/clang/include/clang/AST/CommentSema.h
@@ -211,6 +211,7 @@ class Sema {
   bool isObjCMethodDecl();
   bool isObjCPropertyDecl();
   bool isTemplateOrSpecialization();
+  bool isExplicitFunctionTemplateInstantiation();
   bool isRecordLikeDecl();
   bool isClassOrStructDecl();
   /// \return \c true if the declaration that this comment is attached to
diff --git a/clang/lib/AST/CommentSema.cpp b/clang/lib/AST/CommentSema.cpp
index c7fb6c96fd46f..e74c7cb5ce605 100644
--- a/clang/lib/AST/CommentSema.cpp
+++ b/clang/lib/AST/CommentSema.cpp
@@ -286,6 +286,12 @@ TParamCommandComment *Sema::actOnTParamCommandStart(
       new (Allocator) TParamCommandComment(LocBegin, LocEnd, CommandID,
                                            CommandMarker);
 
+  if (isExplicitFunctionTemplateInstantiation()) {
+    // Do not warn on explicit instantiations, since the documentation
+    // comments are on the primary template.
+    return Command;
+  }
+
   if (!isTemplateOrSpecialization())
     Diag(Command->getLocation(),
          diag::warn_doc_tparam_not_attached_to_a_template_decl)
@@ -854,6 +860,19 @@ bool Sema::isTemplateOrSpecialization() {
   return ThisDeclInfo->getTemplateKind() != DeclInfo::NotTemplate;
 }
 
+bool Sema::isExplicitFunctionTemplateInstantiation() {
+  if (!ThisDeclInfo)
+    return false;
+  if (!ThisDeclInfo->IsFilled)
+    inspectThisDecl();
+  if (const auto *FD = dyn_cast<FunctionDecl>(ThisDeclInfo->CurrentDecl)) {
+    TemplateSpecializationKind TSK = FD->getTemplateSpecializationKind();
+    return (TSK == TSK_ExplicitInstantiationDeclaration) ||
+           (TSK == TSK_ExplicitInstantiationDefinition);
+  }
+  return false;
+}
+
 bool Sema::isRecordLikeDecl() {
   if (!ThisDeclInfo)
     return false;
diff --git a/clang/test/Sema/warn-documentation.cpp b/clang/test/Sema/warn-documentation.cpp
index 0d1faa1b562fe..24a4a22755a36 100644
--- a/clang/test/Sema/warn-documentation.cpp
+++ b/clang/test/Sema/warn-documentation.cpp
@@ -1536,3 +1536,13 @@ template <class T, class = void> constexpr auto var = T{};
 template <typename T> constexpr auto var<T> = T{};
 } // namespace GH144775
 #endif
+
+namespace GH64087
+{
+/// @brief Primary template
+/// @tparam T type
+template <typename T>
+void foo(){}
+
+template void foo<bool>();
+} // namespace GH64087