[clang] Document the warn_unused attribute (PR #201881)

[Aaron Ballman via cfe-commits]

https://github.com/AaronBallman updated https://github.com/llvm/llvm-project/pull/201881

>From e3eb8e1535a7cdc0679c4f41ddecc2f221e82475 Mon Sep 17 00:00:00 2001
From: Aaron Ballman <aaron at aaronballman.com>
Date: Fri, 5 Jun 2026 12:02:03 -0400
Subject: [PATCH 1/5] Document the warn_unused attribute

Basically, this attribute is useful for getting -Wunused-variable
diagnostics from class types with a nontrivial constructor or
destructor.
---
 clang/include/clang/Basic/Attr.td     |  2 +-
 clang/include/clang/Basic/AttrDocs.td | 29 +++++++++++++++++++++++++++
 2 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/clang/include/clang/Basic/Attr.td b/clang/include/clang/Basic/Attr.td
index 7af72333d651c..15e73f4dd66ad 100644
--- a/clang/include/clang/Basic/Attr.td
+++ b/clang/include/clang/Basic/Attr.td
@@ -3898,7 +3898,7 @@ def VecReturn : InheritableAttr {
 def WarnUnused : InheritableAttr {
   let Spellings = [GCC<"warn_unused">];
   let Subjects = SubjectList<[Record]>;
-  let Documentation = [Undocumented];
+  let Documentation = [WarnUnusedDocs];
   let SimpleHandler = 1;
 }
 
diff --git a/clang/include/clang/Basic/AttrDocs.td b/clang/include/clang/Basic/AttrDocs.td
index f54f8e8f90596..d4d9cfa5d3e9c 100644
--- a/clang/include/clang/Basic/AttrDocs.td
+++ b/clang/include/clang/Basic/AttrDocs.td
@@ -388,6 +388,35 @@ pointer, but not any provenance of the allocation:
   }];
 }
 
+def WarnUnusedDocs : Documentation {
+  let Category = DocCatType;
+  let Content = [{
+The ``warn_unused`` attribute can be placed on the declaration of a structure or union type.
+When the ``-Wunused-variable`` diagnostic is enabled, local variables of types which have a non-trivial constructor or destructor are considered "used" by virtue of the constructor or destructor invocations involved.
+Declaring the type with the ``warn_unused`` attribute strengthens the "use" requirements to require a direct access to the variable, such as passing it as an argument to a call, calling a member function on it, taking the address of it, etc.
+
+This attribute is available in both C and C++ language modes but is primarily useful in C++ for classes which have a non-trivial constructor or destructor.
+
+..code-block:: c++
+
+  struct [[gnu::warn_unused]] S {
+    S();
+    ~S();
+  };
+
+  struct T {
+    T();
+    ~T();
+   };
+
+   void func() {
+     S s; // -Wunused-variable warning
+     T t; // No -Wunused-variable warning
+   }
+
+  }];
+}
+
 def MaybeUndefDocs : Documentation {
   let Category = DocCatVariable;
   let Content = [{

>From 9d46b54205485186941e3884dffc6ba5389d6695 Mon Sep 17 00:00:00 2001
From: Aaron Ballman <aaron at aaronballman.com>
Date: Fri, 5 Jun 2026 12:19:41 -0400
Subject: [PATCH 2/5] Add a bit of extra wording

---
 clang/include/clang/Basic/AttrDocs.td | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/clang/include/clang/Basic/AttrDocs.td b/clang/include/clang/Basic/AttrDocs.td
index d4d9cfa5d3e9c..017550e09348a 100644
--- a/clang/include/clang/Basic/AttrDocs.td
+++ b/clang/include/clang/Basic/AttrDocs.td
@@ -395,7 +395,7 @@ The ``warn_unused`` attribute can be placed on the declaration of a structure or
 When the ``-Wunused-variable`` diagnostic is enabled, local variables of types which have a non-trivial constructor or destructor are considered "used" by virtue of the constructor or destructor invocations involved.
 Declaring the type with the ``warn_unused`` attribute strengthens the "use" requirements to require a direct access to the variable, such as passing it as an argument to a call, calling a member function on it, taking the address of it, etc.
 
-This attribute is available in both C and C++ language modes but is primarily useful in C++ for classes which have a non-trivial constructor or destructor.
+This attribute is available in both C and C++ language modes but is primarily useful in C++ for classes which have a non-trivial constructor or destructor but act as a value type rather than an RAII type.
 
 ..code-block:: c++
 

>From 9c416e583bde4af4e5539c3ba7662926da905578 Mon Sep 17 00:00:00 2001
From: Aaron Ballman <aaron at aaronballman.com>
Date: Fri, 5 Jun 2026 12:28:43 -0400
Subject: [PATCH 3/5] Fix sphinx build, hopefully

---
 clang/include/clang/Basic/AttrDocs.td | 1 -
 1 file changed, 1 deletion(-)

diff --git a/clang/include/clang/Basic/AttrDocs.td b/clang/include/clang/Basic/AttrDocs.td
index 017550e09348a..8160f17b42752 100644
--- a/clang/include/clang/Basic/AttrDocs.td
+++ b/clang/include/clang/Basic/AttrDocs.td
@@ -413,7 +413,6 @@ This attribute is available in both C and C++ language modes but is primarily us
      S s; // -Wunused-variable warning
      T t; // No -Wunused-variable warning
    }
-
   }];
 }
 

>From e57e8f553319746d39f74d664451a8732ed8da4f Mon Sep 17 00:00:00 2001
From: Aaron Ballman <aaron at aaronballman.com>
Date: Fri, 5 Jun 2026 13:15:07 -0400
Subject: [PATCH 4/5] Fix sphinx, this time for sure

---
 clang/include/clang/Basic/AttrDocs.td | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/clang/include/clang/Basic/AttrDocs.td b/clang/include/clang/Basic/AttrDocs.td
index 8160f17b42752..887d98ca761cf 100644
--- a/clang/include/clang/Basic/AttrDocs.td
+++ b/clang/include/clang/Basic/AttrDocs.td
@@ -397,7 +397,7 @@ Declaring the type with the ``warn_unused`` attribute strengthens the "use" requ
 
 This attribute is available in both C and C++ language modes but is primarily useful in C++ for classes which have a non-trivial constructor or destructor but act as a value type rather than an RAII type.
 
-..code-block:: c++
+.. code-block:: c++
 
   struct [[gnu::warn_unused]] S {
     S();

>From 6cb548a67819ff14469cfdf745d5a9b3748edee5 Mon Sep 17 00:00:00 2001
From: Aaron Ballman <aaron at aaronballman.com>
Date: Mon, 8 Jun 2026 08:19:47 -0400
Subject: [PATCH 5/5] Updated based on review feedback

---
 clang/include/clang/Basic/AttrDocs.td | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/clang/include/clang/Basic/AttrDocs.td b/clang/include/clang/Basic/AttrDocs.td
index 887d98ca761cf..dab778d4047aa 100644
--- a/clang/include/clang/Basic/AttrDocs.td
+++ b/clang/include/clang/Basic/AttrDocs.td
@@ -393,7 +393,8 @@ def WarnUnusedDocs : Documentation {
   let Content = [{
 The ``warn_unused`` attribute can be placed on the declaration of a structure or union type.
 When the ``-Wunused-variable`` diagnostic is enabled, local variables of types which have a non-trivial constructor or destructor are considered "used" by virtue of the constructor or destructor invocations involved.
-Declaring the type with the ``warn_unused`` attribute strengthens the "use" requirements to require a direct access to the variable, such as passing it as an argument to a call, calling a member function on it, taking the address of it, etc.
+Those constructor or destructor invocations are not considered a use if the type is declared with the ``warn_unused`` attribute.
+The variable is considered used if it is named outside of its declaration.
 
 This attribute is available in both C and C++ language modes but is primarily useful in C++ for classes which have a non-trivial constructor or destructor but act as a value type rather than an RAII type.
 
@@ -409,9 +410,14 @@ This attribute is available in both C and C++ language modes but is primarily us
     ~T();
    };
 
-   void func() {
-     S s; // -Wunused-variable warning
-     T t; // No -Wunused-variable warning
+   int func() {
+     S s1; // -Wunused-variable warning
+     S s2; // No -Wunused-variable warning because of the member access expression below
+     S s3; // No -Wunused-variable warning because of the sizeof operand below
+     T t;  // No -Wunused-variable warning
+
+     s2.~S();
+     return sizeof(s3);
    }
   }];
 }