[llvm-branch-commits] [clang] [analyzer][docs] Add documentation for the UseAfterLifetimeEnd checker (PR #218272)

[Benedek Kaibas via llvm-branch-commits]

https://github.com/benedekaibas updated https://github.com/llvm/llvm-project/pull/218272

>From c9358498e5712cc5d911f5bb50dc5c43167961ee Mon Sep 17 00:00:00 2001
From: benedekaibas <kaibas01 at allegheny.edu>
Date: Sun, 23 Aug 2026 20:22:33 +0200
Subject: [PATCH 1/2] [analyzer][docs] Add documentation for the
 UseAfterLifetimeEnd checker

---
 clang/docs/analyzer/checkers.md | 59 +++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/clang/docs/analyzer/checkers.md b/clang/docs/analyzer/checkers.md
index 70ceae122f959..7ecb1949233f5 100644
--- a/clang/docs/analyzer/checkers.md
+++ b/clang/docs/analyzer/checkers.md
@@ -3348,6 +3348,65 @@ void test(int x) {
 }
 ```
 
+(alpha-core-useafterlifetimeend)=
+
+#### alpha.core.UseAfterLifetimeEnd (C, C++)
+
+Check for returned pointers and references that are bound to an object whose
+lifetime ends when the function returns. The checker only analyzes code that
+is annotated with the `[[clang::lifetimebound]]` attribute. The annotation
+tells the checker which object the returned value is bound to.
+
+```cpp
+int *bound(int *p [[clang::lifetimebound]]);
+
+int *direct_return() {
+  int i = 5; // note: 'i' initialized here
+  return bound(&i); // warn: returning value bound to 'i' that will go
+                    //       out of scope
+}
+```
+
+The attribute states that the returned value may refer to the annotated
+parameter or to the object the function is called on. These are the two
+places where the attribute can be applied.
+
+```cpp
+struct Wrapper {
+  int value;
+  int &get() [[clang::lifetimebound]] { return value; }
+};
+
+int &method_return() {
+  Wrapper w;
+  return w.get(); // warn: returning value bound to 'w' that will go out
+                  //       of scope
+}
+```
+
+{ref}`core-stackaddressescape` reports returning the address of a local object
+directly. This checker extends that detection through functions that are
+annotated with `[[clang::lifetimebound]]`.
+
+{ref}`alpha-core-danglingptrderef` reports the use of a dangling pointer inside
+a function while this checker reports the returned value at the point where the
+function returns.
+
+{ref}`cplusplus-innerpointer` reports similar errors for inner pointers of C++
+containers that are used after re/deallocation without relying on annotations.
+
+**Limitations**
+
+The checker trusts the annotation, so any incorrect annotation can cause false
+positives.
+
+A dangling pointer that is held by a compound object (a struct field) is not
+tracked, so returning such an object is not reported.
+
+Only objects whose memory region is on the stack are tracked. A returned value
+that is bound to heap-allocated memory is not reported. Interoperability
+between this checker and {ref}`unix-malloc` would address this limitation.
+
 (alpha-core-storetoimmutable)=
 
 #### alpha.core.StoreToImmutable (C, C++)

>From d99278ba1be14394bc61c2c482fd9939928aca27 Mon Sep 17 00:00:00 2001
From: benedekaibas <kaibas01 at allegheny.edu>
Date: Sun, 23 Aug 2026 21:12:59 +0200
Subject: [PATCH 2/2] Resolve nits from superseeded PR review.

---
 clang/docs/analyzer/checkers.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/clang/docs/analyzer/checkers.md b/clang/docs/analyzer/checkers.md
index 7ecb1949233f5..f6e72c776e3fe 100644
--- a/clang/docs/analyzer/checkers.md
+++ b/clang/docs/analyzer/checkers.md
@@ -3367,9 +3367,10 @@ int *direct_return() {
 }
 ```
 
-The attribute states that the returned value may refer to the annotated
-parameter or to the object the function is called on. These are the two
-places where the attribute can be applied.
+The attribute states that the returned value is dangling after the lifetime
+of the annotated parameter, or of the implicit object argument, has ended.
+Refer to the [documentation](https://clang.llvm.org/docs/AttributeReference.html#lifetimebound)
+of this Clang attribute.
 
 ```cpp
 struct Wrapper {
@@ -3404,8 +3405,7 @@ A dangling pointer that is held by a compound object (a struct field) is not
 tracked, so returning such an object is not reported.
 
 Only objects whose memory region is on the stack are tracked. A returned value
-that is bound to heap-allocated memory is not reported. Interoperability
-between this checker and {ref}`unix-malloc` would address this limitation.
+that is bound to heap-allocated memory is not reported.
 
 (alpha-core-storetoimmutable)=