[analyzer][NFC] Add some docs for LazyCompoundValue

[Szelethus]

Yes, I basically copy-pasted some posts from discord and Artem's book, but these make for a rather decent docs.

[llvmbot]

@llvm/pr-subscribers-clang

@llvm/pr-subscribers-clang-static-analyzer-1

Author: Kristóf Umann (Szelethus)

Changes

Yes, I basically copy-pasted some posts from discord and Artem's book, but these make for a rather decent docs.

---

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

1 Files Affected:

• (modified) clang/include/clang/StaticAnalyzer/Core/PathSensitive/SVals.h (+39)

diff --git a/clang/include/clang/StaticAnalyzer/Core/PathSensitive/SVals.h b/clang/include/clang/StaticAnalyzer/Core/PathSensitive/SVals.h
index 3a4b087257149..e44cda50ef21d 100644
--- a/clang/include/clang/StaticAnalyzer/Core/PathSensitive/SVals.h
+++ b/clang/include/clang/StaticAnalyzer/Core/PathSensitive/SVals.h
@@ -326,6 +326,12 @@ class LocAsInteger : public NonLoc {
   static bool classof(SVal V) { return V.getKind() == LocAsIntegerKind; }
 };
 
+/// The simplest example of a concrete compound value is nonloc::CompoundVal,
+/// which represents a concrete r-value of an initializer-list or a string.
+/// Internally, it contains an llvm::ImmutableList of SVal's stored inside the
+/// literal.
+///
+/// Source: https://github.com/haoNoQ/clang-analyzer-guide, v0.1, section 5.3.2.
 class CompoundVal : public NonLoc {
   friend class ento::SValBuilder;
 
@@ -346,6 +352,39 @@ class CompoundVal : public NonLoc {
   static bool classof(SVal V) { return V.getKind() == CompoundValKind; }
 };
 
+/// The simplest example of a concrete compound value is nonloc::CompoundVal,
+/// which represents a concrete r-value of an initializer-list or a string.
+/// Internally, it contains an llvm::ImmutableList of SVal's stored inside the
+/// literal.
+///
+/// However, there is another compound value used in the analyzer, which appears
+/// much more often during analysis, which is nonloc::LazyCompoundVal. 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 re- ferred 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 copy of the whole Store object, obtained from the ProgramState in
+///     which it was created.
+///
+/// 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.
+///
+/// Source: https://github.com/haoNoQ/clang-analyzer-guide, v0.1, section 5.3.2.
+///
+/// If you ever need to see if a LazyCompoundVal is fully or partially
+/// (un)initialized, you can iterBindings(). This is non-typechecked lookup
+/// (i.e., you cannot figure out which specific sub-region is initialized by the
+/// value you look at, you only get a byte offset). You can also improve
+/// iterBindings() to make it possible to restrict the iteration to a single
+/// cluster, because within the LazyCompoundVal’s Store only the cluster that
+/// corresponds to the LazyCompoundVal’s parent region is relevant.
+///
+/// Source: https://discourse.llvm.org/t/analyzer-for-the-undefined-value-of-array-element-the-tracking-information-is-incomplete/49372/2
 class LazyCompoundVal : public NonLoc {
   friend class ento::SValBuilder;
 

[github-actions]

✅ With the latest revision this PR passed the C/C++ code formatter.

[NagyDonat]

I'm really happy that you decided to document these 😄

[steakhal]

Makes sense. It's good to see some love for the docs.

[haoNoQ]

Thanks a lot!! Some comments are very much overdue here.

[Szelethus]

I'd also love to see some docs for Loc and NonLoc, because I recall some angry looks from years ago when I touched those on their own, but I can barely recall them :( As well as some docs for the various ProgramState::getSVal methods...

[steakhal]

I think it's already in a good shape. I found barely any problems with the wording.

[steakhal]

To be fair, I don't really understand this.

To me, this region is the region that one would need to query from the associated Store to get the value this LazyCompoundValue actually boils down to.
So, a region, like every other region, only defines a memory location (an l-value), and there is not much one could do with such a region. But I find this true for any other MemRegion anywhere in the engine.

Probably I miss something, as I don't usually deal with LCVs, and it's been a while I last touched them.
So, to summarize, I don't really understand what immaterial means in this context or understand why we mention it for LCV::getRegion() instead of mention this for a MemRegion.

[Szelethus]

@haoNoQ I can't really counter this, can you help us out a bit? :)

[Szelethus]

I decided to merge this. We are still miles ahead with these docs, and I don't wanna accidentally forget the PR.