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

[Benedek Kaibas via llvm-branch-commits]

================
@@ -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 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 {
+  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
----------------
benedekaibas wrote:

Applied changes here: [aff169f](https://github.com/llvm/llvm-project/pull/218272/commits/aff169f255ec2fbe2896a0d523db63994285218d)

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