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

[Gábor Horváth via cfe-commits]

================
@@ -0,0 +1,600 @@
+========================
+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 exclusivity enforcement (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. While it does
+not require lifetime annotations to get started, in their absence, the analysis
+treats function calls optimistically, assuming no lifetime effects, thereby potentially missing dangling pointer issues. As more functions are annotated
+with attributes like `clang::lifetimebound <https://clang.llvm.org/docs/AttributeReference.html#lifetimebound>`_, `gsl::Owner <https://clang.llvm.org/docs/AttributeReference.html#gsl-owner>`_, and
+`gsl::Pointer <https://clang.llvm.org/docs/AttributeReference.html#gsl-pointer>`_, the analysis can see through these lifetime contracts and enforce
+lifetime safety at call sites with higher accuracy. This approach supports
+gradual adoption in existing codebases. 
+
+.. note::
+  This analysis is designed for bug finding, not verification. It may miss some
+  lifetime issues and can produce false positives. It does not guarantee the
----------------
Xazax-hun wrote:

Nit: the last sentence is not finished.

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