[clang] [analyzer][NFC] Add some docs for LazyCompoundValue (PR #97407)

[Balazs Benics via cfe-commits]

=?utf-8?q?Kristóf?= Umann <dkszelethus at gmail.com>,
=?utf-8?q?Kristóf?= Umann <dkszelethus at gmail.com>,
=?utf-8?q?Kristóf?= Umann <dkszelethus at gmail.com>,
=?utf-8?q?Kristóf?= Umann <dkszelethus at gmail.com>
Message-ID:
In-Reply-To: <llvm.org/llvm/llvm-project/pull/97407 at github.com>


================
@@ -346,6 +350,36 @@ class CompoundVal : public NonLoc {
   static bool classof(SVal V) { return V.getKind() == CompoundValKind; }
 };
 
+/// While nonloc::CompoundVal covers a few simple use cases,
+/// nonloc::LazyCompoundVal is a more performant and flexible way to represent
+/// an rvalue of record type, so it shows up much more frequently during
+/// analysis. This value is an r-value that represents a snapshot of any
+/// structure "as a whole" at a given moment during the analysis. Such value is
+/// already quite far from being referred to as "concrete", as many fields
+/// inside it would be unknown or symbolic. nonloc::LazyCompoundVal operates by
+/// storing two things:
+///   * a reference to the TypedValueRegion being snapshotted (yes, it is always
+///     typed), and also
+///  * a reference to the whole Store object, obtained from the ProgramState in
+///    which the nonloc::LazyCompoundVal was created.
+///
+/// Note that the old ProgramState and its Store is kept alive during the
+/// analysis because these are immutable functional data structures and each new
+/// Store value is represented as "earlier Store" + "additional binding".
+///
+/// Essentially, nonloc::LazyCompoundVal is a performance optimization for the
+/// analyzer. Because Store is immutable, creating a nonloc::LazyCompoundVal is
+/// a very cheap operation. Note that the Store contains all region bindings in
+/// the program state, not only related to the region. Later, if necessary, such
+/// value can be unpacked -- eg. when it is assigned to another variable.
+///
+/// If you ever need inspect the contents of the LazyCompoundVal, you can use
----------------
steakhal wrote:

```suggestion
/// If you ever need to inspect the contents of the LazyCompoundVal, you can use
```

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