update docs with more promotion/narrowing info

Signed-off-by: Justin Stitt <[email protected]>

Author: JustinStitt

clang/docs/OverflowBehaviorTypes.rst

@@ -43,6 +43,10 @@ Where ``behavior`` can be one of the following:
 
 This attribute can be applied to ``typedef`` declarations and to integer types directly.
 
+Arithmetic operations containing one or more overflow behavior types may have
+result types that do not match standard integer promotion rules. The
+characteristics of result types across all scenarios are described under `Promotion Rules`_.
+
 Examples
 ========
 
@@ -75,46 +79,6 @@ integral types.
 Note that C++ overload set formation rules treat promotions to and from
 overflow behavior types the same as normal integral promotions and conversions.
 
-Interaction with Command-Line Flags and Sanitizer Special Case Lists
-====================================================================
-
-The ``overflow_behavior`` attribute interacts with sanitizers, ``-ftrapv``,
-``-fwrapv``, and Sanitizer Special Case Lists (SSCL) by wholly overriding these
-global flags. The following table summarizes the interactions:
-
-.. list-table:: Overflow Behavior Precedence
-   :widths: 15 15 15 15 20 15
-   :header-rows: 1
-
-   * - Behavior
-     - Default(No Flags)
-     - -ftrapv
-     - -fwrapv
-     - Sanitizers
-     - SSCL
-   * - ``overflow_behavior(wrap)``
-     - Wraps
-     - No trap
-     - Wraps
-     - No report
-     - Overrides SSCL
-   * - ``overflow_behavior(no_wrap)``
-     - Traps
-     - Traps
-     - Traps
-     - Reports
-     - Overrides SSCL
-
-It is important to note the distinction between signed and unsigned types. For
-unsigned integers, which wrap on overflow by default, ``overflow_behavior(no_wrap)``
-is particularly useful for enabling overflow checks. For signed integers, whose
-overflow behavior is undefined by default, ``overflow_behavior(wrap)`` provides
-a guaranteed wrapping behavior.
-
-The ``overflow_behavior`` attribute can be used to override the behavior of
-entries from a :doc:`SanitizerSpecialCaseList`. This is useful for allowlisting
-specific types into overflow instrumentation.
-
 Promotion Rules
 ===============
 
@@ -123,6 +87,9 @@ specified overflow behavior throughout an arithmetic expression. They differ
 from standard C/C++ integer promotions but in a predictable way, similar to
 how ``_Complex`` and ``_BitInt`` have their own promotion rules.
 
+The resulting type characteristics for overflow behavior types (OBTs) across a
+variety of scenarios is detailed below.
+
 * **OBT and Standard Integer Type**: In an operation involving an overflow
   behavior type (OBT) and a standard integer type, the result will have the
   type of the OBT, including its overflow behavior, sign, and bit-width. The
@@ -156,6 +123,59 @@ how ``_Complex`` and ``_BitInt`` have their own promotion rules.
   Regardless, the resulting type matches the bit-width, sign and behavior of
   the ``no_wrap`` type.
 
+.. list-table:: Promotion Rules Summary
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Operation Type
+     - Result Type
+   * - OBT + Standard Integer
+     - OBT type (preserves overflow behavior, sign, and bit-width)
+   * - Same Kind OBTs (both ``wrap`` or both ``no_wrap``)
+     - Larger bit-width; unsigned favored if same width
+   * - Different Kind OBTs (``wrap`` + ``no_wrap``)
+     - ``no_wrap`` type (matches ``no_wrap`` operand's characteristics)
+
+Interaction with Command-Line Flags and Sanitizer Special Case Lists
+====================================================================
+
+The ``overflow_behavior`` attribute interacts with sanitizers, ``-ftrapv``,
+``-fwrapv``, and Sanitizer Special Case Lists (SSCL) by wholly overriding these
+global flags. The following table summarizes the interactions:
+
+.. list-table:: Overflow Behavior Precedence
+   :widths: 15 15 15 15 20 15
+   :header-rows: 1
+
+   * - Behavior
+     - Default(No Flags)
+     - -ftrapv
+     - -fwrapv
+     - Sanitizers
+     - SSCL
+   * - ``overflow_behavior(wrap)``
+     - Wraps
+     - Wraps
+     - Wraps
+     - No report
+     - Overrides SSCL
+   * - ``overflow_behavior(no_wrap)``
+     - Traps
+     - Traps
+     - Traps
+     - Reports
+     - Overrides SSCL
+
+It is important to note the distinction between signed and unsigned types. For
+unsigned integers, which wrap on overflow by default, ``overflow_behavior(no_wrap)``
+is particularly useful for enabling overflow checks. For signed integers, whose
+overflow behavior is undefined by default, ``overflow_behavior(wrap)`` provides
+a guaranteed wrapping behavior.
+
+The ``overflow_behavior`` attribute can be used to override the behavior of
+entries from a :doc:`SanitizerSpecialCaseList`. This is useful for allowlisting
+specific types into overflow instrumentation.
+
 Diagnostics
 ===========
 

clang/docs/UndefinedBehaviorSanitizer.rst

@@ -390,6 +390,20 @@ arithmetic operations on that type should wrap on overflow. This can be used to
 disable overflow sanitization for specific types, while leaving it enabled for
 all other types.
 
+The ``overflow_behavior`` attribute not only affects UBSan instrumentation
+but also changes the fundamental overflow behavior of arithmetic operations
+on the annotated type. Operations on types marked with ``wrap`` will have
+well-defined wrapping semantics, while operations on types marked with
+``no_wrap`` will be checked for overflow (regardless of global flags like
+``-fwrapv``).
+
+The attribute also affects implicit type promotion rules: when an overflow
+behavior type participates in arithmetic operations with standard integer
+types, the result maintains the overflow behavior type's characteristics,
+including its bit-width. This means annotated types can preserve narrower
+widths that would normally be promoted, allowing operations to stay within
+the constraints of the smallest annotated type in the expression.
+
 For more information, see :doc:`OverflowBehaviorTypes`.
 
 Enforcing Overflow Instrumentation with ``__attribute__((overflow_behavior(no_wrap)))``