[clang] [llvm] [clang] Implement lifetime analysis for lifetime_capture_by(X) (PR #115921)

[Utkarsh Saxena via llvm-commits]

================
@@ -3925,13 +3925,20 @@ def LifetimeCaptureByDocs : Documentation {
 parameter or implicit object parameter indicates that that objects that are referred to
 by that parameter may also be referred to by the capturing entity ``X``.
 
-By default, a reference is considered to refer to its referenced object, a
-pointer is considered to refer to its pointee, a ``std::initializer_list<T>``
-is considered to refer to its underlying array, and aggregates (arrays and
-simple ``struct``\s) are considered to refer to all objects that their
-transitive subobjects refer to.
+By default:
----------------
usx95 wrote:

We are talking about the parameter and not the capturing entity X. Added more details to the docs.

The entity to which the reference refer to is important to outlive the capturing entity.

For example,
`void foo(const std::string_view& s [[clang::lifetime_capture_by(x), X &x)`
1. In `foo(std::string(), x)`, the param `s` refers to a temporary `std::string()`.
2. In `std::string local; foo(std::string_view(local), x)`, the param `s` refers to `local`.

Does it make sense now ? PTAL.

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