[clang] [LifetimeSafety] Document record type origin tracking for lifetimebound calls (PR #189508)

[Zhijie Wang via cfe-commits]

https://github.com/aeft created https://github.com/llvm/llvm-project/pull/189508

None

>From 273448c06ad150e496d2b7d4accf308c7e39f3c7 Mon Sep 17 00:00:00 2001
From: Zhijie Wang <yesterda9 at gmail.com>
Date: Mon, 30 Mar 2026 16:51:34 -0700
Subject: [PATCH] [LifetimeSafety] Document record type origin tracking for
 lifetimebound calls

---
 clang/docs/LifetimeSafety.rst | 27 +++++++++++++++++++++++++--
 1 file changed, 25 insertions(+), 2 deletions(-)

diff --git a/clang/docs/LifetimeSafety.rst b/clang/docs/LifetimeSafety.rst
index ac76231dede67..efebb61699ee7 100644
--- a/clang/docs/LifetimeSafety.rst
+++ b/clang/docs/LifetimeSafety.rst
@@ -145,8 +145,8 @@ LifetimeBound
 
 The ``[[clang::lifetimebound]]`` attribute can be applied to function parameters
 or to the implicit ``this`` parameter of a method (by placing it after the
-method declarator). It indicates that the returned pointer or reference becomes
-invalid when the attributed parameter or ``this`` object is destroyed.
+method declarator). It indicates that the returned value becomes invalid when
+the attributed parameter or ``this`` object is destroyed.
 This is crucial for functions that return views or references to their
 arguments.
 
@@ -172,6 +172,29 @@ Without ``[[clang::lifetimebound]]`` on ``getView()``, the analysis would not
 know that the value returned by ``getView()`` depends on the temporary
 ``MyOwner`` object, and it would not be able to diagnose the dangling ``sv``.
 
+The analysis also tracks record types returned from functions and constructors
+with ``[[clang::lifetimebound]]`` parameters:
+
+.. code-block:: c++
+
+  #include <string>
+
+  struct S {
+    S(const std::string &s [[clang::lifetimebound]]);
+  };
+
+  S getS(const std::string &s [[clang::lifetimebound]]);
+
+  void test() {
+    S a(std::string("temp")); // warning: object whose reference is captured does not live long enough
+                              // note: destroyed here
+    (void)a;                  // note: later used here
+
+    S b = getS(std::string("temp")); // warning: object whose reference is captured does not live long enough
+                                     // note: destroyed here
+    (void)b;                         // note: later used here
+  }
+
 For more details, see `lifetimebound <https://clang.llvm.org/docs/AttributeReference.html#lifetimebound>`_.
 
 NoEscape