documentation updates

Author: usx95

clang/include/clang/Analysis/Analyses/LifetimeSafety/Checker.h

@@ -6,11 +6,12 @@
 //
 //===----------------------------------------------------------------------===//
 //
-// This file provides the entry point for lifetime checking, which detects
-// use-after-free errors by checking if live origins hold loans that have
-// expired.
+// This file defines and enforces the lifetime safety policy. It detects
+// use-after-free errors by examining loan expiration points and checking if
+// any live origins hold the expired loans.
 //
 //===----------------------------------------------------------------------===//
+
 #ifndef LLVM_CLANG_ANALYSIS_ANALYSES_LIFETIMESAFETY_CHECKER_H
 #define LLVM_CLANG_ANALYSIS_ANALYSES_LIFETIMESAFETY_CHECKER_H
 

clang/include/clang/Analysis/Analyses/LifetimeSafety/LifetimeSafety.h

@@ -6,8 +6,10 @@
 //
 //===----------------------------------------------------------------------===//
 //
-// This file defines the entry point for a dataflow-based static analysis
-// that checks for C++ lifetime violations.
+// This file defines the main entry point and orchestrator for the C++ Lifetime
+// Safety Analysis. It coordinates the entire analysis pipeline: fact
+// generation, loan propagation, live origins analysis, and enforcement of
+// lifetime safety policy.
 //
 // The analysis is based on the concepts of "origins" and "loans" to track
 // pointer lifetimes and detect issues like use-after-free and dangling

clang/include/clang/Analysis/Analyses/LifetimeSafety/LiveOrigins.h

@@ -8,10 +8,11 @@
 //
 // This file defines the LiveOriginAnalysis, a backward dataflow analysis that
 // determines which origins are "live" at each program point. An origin is
-// "live" at a program point if there's a potential future use of the pointer it
-// represents. Liveness is "generated" by a read of origin's loan set (e.g., a
-// `UseFact`) and is "killed" (i.e., it stops being live) when its loan set is
-// overwritten (e.g. a OriginFlow killing the destination origin).
+// "live" at a program point if there's a potential future use of a pointer it
+// is associated with. Liveness is "generated" by a use of an origin (e.g., a
+// `UseFact` from a read of a pointer) and is "killed" (i.e., it stops being
+// live) when the origin is replaced by flowing a different origin into it
+// (e.g., an OriginFlow from an assignment that kills the destination).
 //
 // This information is used for detecting use-after-free errors, as it allows us
 // to check if a live origin holds a loan to an object that has already expired.
@@ -42,8 +43,8 @@ struct LivenessInfo {
   /// multiple uses along different paths, this will point to the use appearing
   /// earlier in the translation unit.
   /// This is 'null' when the origin is not live.
-
   const UseFact *CausingUseFact;
+
   /// The kind of liveness of the origin.
   /// `Must`: The origin is live on all control-flow paths from the current
   /// point to the function's exit (i.e. the current point is dominated by a set
@@ -79,7 +80,7 @@ class LiveOriginsAnalysis {
   ~LiveOriginsAnalysis();
 
   /// Returns the set of origins that are live at a specific program point,
-  /// along with the confidence level of their liveness.
+  /// along with the the details of the liveness.
   LivenessMap getLiveOriginsAt(ProgramPoint P) const;
 
   // Dump liveness values on all test points in the program.