[clang] [Clang] Clarify the `[[trivial_abi]]` documentation. (PR #143243)

[Corentin Jabot via cfe-commits]

https://github.com/cor3ntin updated https://github.com/llvm/llvm-project/pull/143243

>From 9b6128211ea4a442ecded830c77c60387245bb89 Mon Sep 17 00:00:00 2001
From: Corentin Jabot <corentinjabot at gmail.com>
Date: Sat, 7 Jun 2025 10:24:26 +0200
Subject: [PATCH 1/2] [Clang] Clarify the `[[trivial_abi]]` documentation.

Fixes #36667
---
 clang/include/clang/Basic/AttrDocs.td | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/clang/include/clang/Basic/AttrDocs.td b/clang/include/clang/Basic/AttrDocs.td
index 40b9f8142bb69..19d5a76246bf0 100644
--- a/clang/include/clang/Basic/AttrDocs.td
+++ b/clang/include/clang/Basic/AttrDocs.td
@@ -4431,7 +4431,11 @@ destroy the object before returning. The lifetime of the copy of the parameter
 in the caller ends without a destructor call when the call begins.
 
 If a type is trivial for the purpose of calls, it is assumed to be trivially
-relocatable for the purpose of ``__is_trivially_relocatable``.
+relocatable for the purpose of ``__is_trivially_relocatable`` and
+``__builtin_is_cpp_trivially_relocatable``.
+The copy constructor of a an object of such type might not be called
+when the object is passed to a function. Therefore, the ``trivial_abi``
+attribute should not be applied to objects that contain pointer to themselves.
 
 Attribute ``trivial_abi`` has no effect in the following cases:
 

>From 002d009ec2902b8743faae75504ac4bbba6850ff Mon Sep 17 00:00:00 2001
From: Corentin Jabot <corentinjabot at gmail.com>
Date: Mon, 9 Jun 2025 17:26:04 +0200
Subject: [PATCH 2/2] Apply Erich's feedback after some offline bike-shedding

---
 clang/include/clang/Basic/AttrDocs.td | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/clang/include/clang/Basic/AttrDocs.td b/clang/include/clang/Basic/AttrDocs.td
index 19d5a76246bf0..89572793cd143 100644
--- a/clang/include/clang/Basic/AttrDocs.td
+++ b/clang/include/clang/Basic/AttrDocs.td
@@ -4433,9 +4433,12 @@ in the caller ends without a destructor call when the call begins.
 If a type is trivial for the purpose of calls, it is assumed to be trivially
 relocatable for the purpose of ``__is_trivially_relocatable`` and
 ``__builtin_is_cpp_trivially_relocatable``.
-The copy constructor of a an object of such type might not be called
-when the object is passed to a function. Therefore, the ``trivial_abi``
-attribute should not be applied to objects that contain pointer to themselves.
+When a type marked with ``[[trivial_abi]]`` is used as a function argument,
+the compiler may omit the call to the copy constructor.
+Thus, side effects of the copy constructor are potentially not performed.
+For example, objects that contain pointers to themselves or otherwise depend
+on their address (or the address or their subobjects) should not be declared
+``[[trivial_abi]]``.
 
 Attribute ``trivial_abi`` has no effect in the following cases: