[clang] [Clang] Add AttrDocs entry for OverflowBehavior (PR #203392)

[Justin Stitt via cfe-commits]

https://github.com/JustinStitt updated https://github.com/llvm/llvm-project/pull/203392

>From 02bf80112c24147e57918cf814be2098e57dca8f Mon Sep 17 00:00:00 2001
From: Justin Stitt <justinstitt at google.com>
Date: Thu, 11 Jun 2026 13:35:00 -0700
Subject: [PATCH 1/3] [Clang] Add AttrDocs entry for OverflowBehavior

These docs were previously missing. Basically just add what was in the
formal docs here.

Fixes: https://github.com/llvm/llvm-project/issues/203322

Signed-off-by: Justin Stitt <justinstitt at google.com>
---
 clang/include/clang/Basic/Attr.td     |  2 +-
 clang/include/clang/Basic/AttrDocs.td | 45 +++++++++++++++++++++++++++
 2 files changed, 46 insertions(+), 1 deletion(-)

diff --git a/clang/include/clang/Basic/Attr.td b/clang/include/clang/Basic/Attr.td
index 7f7e9489782a7..b5c50a0d16e51 100644
--- a/clang/include/clang/Basic/Attr.td
+++ b/clang/include/clang/Basic/Attr.td
@@ -5477,7 +5477,7 @@ def OverflowBehavior : TypeAttr {
   let Args = [IdentifierArgument<"BehaviorKind">];
   let Subjects = SubjectList<[Var, TypedefName, Field], WarnDiag,
                              "variables, typedefs, and data members">;
-  let Documentation = [Undocumented];
+  let Documentation = [OverflowBehaviorDocs];
 }
 
 def Personality : InheritableAttr {
diff --git a/clang/include/clang/Basic/AttrDocs.td b/clang/include/clang/Basic/AttrDocs.td
index dab778d4047aa..280b75957c971 100644
--- a/clang/include/clang/Basic/AttrDocs.td
+++ b/clang/include/clang/Basic/AttrDocs.td
@@ -10051,6 +10051,51 @@ The following aspects are currently supported:
   }];
 }
 
+def OverflowBehaviorDocs : Documentation {
+  let Category = DocCatType;
+  let Content = [{
+The ``overflow_behavior`` attribute provides fine-grained, type-level control
+over how arithmetic operations on an integer type behave on overflow. It may be
+applied to a ``typedef``, to a variable or data member, or to an integer type
+directly, and accepts one of two behaviors as its argument:
+
+* ``wrap``: arithmetic on the attributed type wraps on overflow, using two's
+  complement semantics. This is equivalent to ``-fwrapv`` but scoped to the
+  attributed type, and works for both signed and unsigned types. UBSan's
+  ``signed-integer-overflow``, ``unsigned-integer-overflow``,
+  ``implicit-signed-integer-truncation``, and
+  ``implicit-unsigned-integer-truncation`` checks are suppressed for the type.
+
+* ``trap``: arithmetic on the attributed type is checked for overflow, enabling
+  overflow checks for the type even when ``-fwrapv`` is in effect globally.
+
+.. code-block:: c++
+
+  typedef unsigned int __attribute__((overflow_behavior(trap))) non_wrapping_uint;
+
+  non_wrapping_uint add_one(non_wrapping_uint a) {
+    return a + 1; // Overflow is checked for this operation.
+  }
+
+  int mul_alot(int n) {
+    int __attribute__((overflow_behavior(wrap))) a = n;
+    return a * 1337; // Overflow is not checked and is well-defined.
+  }
+
+The keyword spellings ``__ob_wrap`` and ``__ob_trap`` are equivalent to
+``overflow_behavior(wrap)`` and ``overflow_behavior(trap)`` respectively.
+
+The attribute wholly overrides global flags (``-ftrapv``, ``-fwrapv``,
+sanitizers, and Sanitizer Special Case Lists) for the attributed type. It can
+only be applied to integer types.
+
+This feature is experimental and must be enabled with the ``-cc1`` option
+``-fexperimental-overflow-behavior-types``. For full details on promotion and
+conversion rules, pointer semantics, diagnostics, and interaction with
+sanitizers, see :doc:`OverflowBehaviorTypes`.
+  }];
+}
+
 def MSStructDocs : Documentation {
   let Category = DocCatDecl;
   let Content = [{

>From ab67efe26d799cfb5c0ad95340a90393edb6b148 Mon Sep 17 00:00:00 2001
From: Justin Stitt <justinstitt at google.com>
Date: Thu, 11 Jun 2026 16:07:57 -0700
Subject: [PATCH 2/3] remove from undocumented-attrs.cpp

Signed-off-by: Justin Stitt <justinstitt at google.com>
---
 clang/test/AST/undocumented-attrs.cpp | 1 -
 1 file changed, 1 deletion(-)

diff --git a/clang/test/AST/undocumented-attrs.cpp b/clang/test/AST/undocumented-attrs.cpp
index c7a2c74631ea2..da00c90e70ffb 100644
--- a/clang/test/AST/undocumented-attrs.cpp
+++ b/clang/test/AST/undocumented-attrs.cpp
@@ -69,7 +69,6 @@ CHECK-NEXT:	ObjCPreciseLifetime
 CHECK-NEXT:	ObjCRequiresPropertyDefs
 CHECK-NEXT:	ObjCReturnsInnerPointer
 CHECK-NEXT:	ObjCRootClass
-CHECK-NEXT:	OverflowBehavior
 CHECK-NEXT:	Packed
 CHECK-NEXT:	Pascal
 CHECK-NEXT:	PointerFieldProtection

>From 068cb2291ce227d301dd83d0d29448999cb4c94a Mon Sep 17 00:00:00 2001
From: Justin Stitt <justinstitt at google.com>
Date: Fri, 12 Jun 2026 08:02:38 -0700
Subject: [PATCH 3/3] further fix tests

Signed-off-by: Justin Stitt <justinstitt at google.com>
---
 clang/test/AST/undocumented-attrs.cpp | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/clang/test/AST/undocumented-attrs.cpp b/clang/test/AST/undocumented-attrs.cpp
index da00c90e70ffb..eeebd7f938644 100644
--- a/clang/test/AST/undocumented-attrs.cpp
+++ b/clang/test/AST/undocumented-attrs.cpp
@@ -90,4 +90,4 @@ CHECK-NEXT:	Visibility
 CHECK-NEXT:	WeakImport
 CHECK-NEXT:	WeakRef
 CHECK-NEXT:	WorkGroupSizeHint
-CHECK-NEXT: Total: 85
+CHECK-NEXT: Total: 84