[clang] [LifetimeSafety] Add user documentation (PR #183058)

[Utkarsh Saxena via cfe-commits]

================
@@ -0,0 +1,598 @@
+========================
+Lifetime Safety Analysis
+========================
+
+.. contents::
+   :local:
+
+Introduction
+============
+
+Clang Lifetime Safety Analysis is a C++ language extension which warns about
+potential dangling pointer defects in code. The analysis aims to detect
+when a pointer, reference or view type (such as ``std::string_view``) refers to an object
+that is no longer alive, a condition that leads to use-after-free bugs and
+security vulnerabilities. Common examples include pointers to stack variables
+that have gone out of scope, fields holding views to stack-allocated objects
+(dangling-field), returning pointers/references to stack variables 
+(return stack address) or iterators into container elements invalidated by
+container operations (e.g., ``std::vector::push_back``)
+
+The analysis design is inspired by `Polonius, the Rust borrow checker <https://github.com/rust-lang/polonius>`_,
+but adapted to C++ idioms and constraints, such as the lack of borrow checker exclusivity (alias-xor-mutability). 
+Further details on the analysis method can be found in the `RFC on Discourse <https://discourse.llvm.org/t/rfc-intra-procedural-lifetime-analysis-in-clang/86291/>`_.
+
+This is compile-time analysis; there is no run-time overhead. 
+It tracks pointer validity through intra-procedural data-flow analysis, supporting a form of gradual typing. While it does
----------------
usx95 wrote:

Thanks. Makes sense. I was probably connecting some other dots (like opaque loans and opaque types). Better to stay clear of that in the docs.

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