Update comments

Author: Your Name

lib/analyzer.h

@@ -156,13 +156,9 @@ struct Analyzer {
             Quiet = (1 << 0),
             Absolute = (1 << 1),
             ContainerEmpty = (1 << 2),
-            // The branch this condition guards is still pending traversal (it is walked by a
-            // separate path), so this assume must not record the program state at the branch
-            // boundaries - those states would be premature. When this is not set the branch has
-            // already been traversed and control is continuing past it, so the assumed state is
-            // anchored at the block's end (see the analyzer's assume()): this keeps assumptions on
-            // variables modified inside the block from being discarded as "modified" once control
-            // leaves it.
+            // The branch this condition guards is not traversed yet (a separate path walks it), so
+            // the assume must not record the program state at the branch boundaries - they would be
+            // premature. When unset, the branch has been traversed and control is leaving it.
             Pending = (1 << 3),
         };
     };

lib/forwardanalyzer.cpp

@@ -426,9 +426,8 @@ namespace {
                 branch.escape = true;
                 branch.escapeUnknown = false;
             } else {
-                // Detect an escape that the traversal did not flag (e.g. an unknown noreturn call);
-                // isEscapeScope also reports a possible (unknown) escape via escapeUnknown. Such a
-                // branch may not fall through, so the fork must not continue past it.
+                // Detect an escape the traversal did not flag (e.g. an unknown noreturn call);
+                // escapeUnknown reports a possible (unknown) escape.
                 branch.escape = isEscapeScope(branch.endBlock, branch.escapeUnknown);
                 if (terminate != Analyzer::Terminate::None && terminate != Analyzer::Terminate::Modified) {
                     branch.action |= analyzeScope(branch.endBlock);
@@ -679,10 +678,9 @@ namespace {
                         Token* condTok = getCondTokFromEnd(tok);
                         if (!condTok)
                             return Break();
-                        // When leaving the 'then' branch, control only reaches here when the
-                        // condition was true if the 'else' branch escapes (e.g. it returns). In that
-                        // case the value established in 'then' is still definite, so keep it known
-                        // instead of lowering it to possible.
+                        // When the 'else' branch escapes (e.g. returns), control can only continue
+                        // here via the 'then' branch, so the value established there is still
+                        // definite - keep it known instead of lowering to possible.
                         bool elseEscape = false;
                         bool unknownEscape = false;
                         if (!inLoop && !inElse && hasElse)
@@ -788,18 +786,18 @@ namespace {
                         } else {
                             const bool conditional = stopOnCondition(condTok);
                             // The value only flows into the then-branch when the condition can split
-                            // it. For an opaque or correlated condition (e.g. 'if (f(x))' or
-                            // 'if (do_write)') it does not really reach there, so fork in analyze-only
-                            // mode: the branch's effect is still tracked but nothing is reported in it.
+                            // it; for an opaque or correlated condition (e.g. 'if (f(x))') it does
+                            // not, so fork in analyze-only mode: the branch's effect is still tracked
+                            // but nothing is reported in it.
                             ForwardTraversal ft = fork(!analyzer->updateScope(thenBranch.endBlock, false));
                             // The branch is traversed below, so don't record its boundary state here.
                             ft.analyzer->assume(condTok, true, Analyzer::Assume::Pending);
                             Progress pThen = ft.updateBranch(thenBranch, depth - 1);
 
-                            // Only commit the condition as false on the main path when it actually
-                            // matters. With an else the else block is traversed below (so suppress the
-                            // boundary state); without one the false path continues past the closing
-                            // brace and must record the assumed state there.
+                            // Commit the condition as false on the main path only when the then-branch
+                            // is dead. The else block, if any, is traversed separately (Pending); with
+                            // no else the false path continues past the closing brace, so record the
+                            // assumed state there (None).
                             if (thenBranch.isDead())
                                 analyzer->assume(condTok, false, hasElse ? Analyzer::Assume::Pending : Analyzer::Assume::None);
                             // The else block is traversed on the main path. If it kills the value

lib/programmemory.cpp

@@ -1308,9 +1308,8 @@ namespace {
     struct Executor {
         ProgramMemory* pm;
         const Settings& settings;
-        // The values that are being tracked by the forward/reverse analysis. These take precedence
-        // over what is stored in the program memory: a tracked value is the authoritative current
-        // value of its expression, so any cached value that depends on it must be re-evaluated.
+        // Values tracked by the forward/reverse analysis. A tracked value is the authoritative
+        // current value of its expression and takes precedence over the program memory.
         const ProgramMemory::Map* vars = nullptr;
         int fdepth = 4;
         int depth = 10;
@@ -1328,9 +1327,8 @@ namespace {
             return it == vars->end() ? nullptr : &it->second;
         }
 
-        // Does the expression read a tracked value? If so, any value cached in the program memory
-        // for it may be stale (the tracked value may have changed since it was cached), so it must
-        // be re-evaluated rather than served from the cache.
+        // Does the expression read a tracked value? If so, any value cached for it may be stale
+        // (the tracked value may have changed since), so it must be re-evaluated, not served cached.
         bool dependsOnTrackedValue(const Token* expr) const {
             if (!vars || vars->empty())
                 return false;
@@ -1637,9 +1635,8 @@ namespace {
                 }
                 return execute(expr->astOperand1());
             }
-            // A tracked value is the authoritative current value of its expression. Write it back
-            // into the program memory when it differs from what is stored, so that later reads see
-            // the same value (matching the substitution done by fillProgramMemoryFromAssignments).
+            // Return the tracked value and write it back when it differs, so later reads see the
+            // same value (as fillProgramMemoryFromAssignments used to do).
             if (const ValueFlow::Value* tracked = getTrackedValue(expr)) {
                 const ValueFlow::Value* stored = pm->getValue(expr->exprId(), /*impossible*/ true);
                 if (!stored || *stored != *tracked)

lib/vf_analyzers.cpp

@@ -678,10 +678,9 @@ struct ValueFlowAnalyzer : Analyzer {
         if (const ValueFlow::Value* v = tok->getKnownValue(ValueFlow::Value::ValueType::INT))
             return {v->intvalue};
         std::vector<MathLib::bigint> result;
-        // The tracked values are authoritative: pass them so a value cached in the program memory
-        // that depends on a tracked value (e.g. 'h(p)' after 'p' was reassigned) is re-evaluated
-        // rather than served stale. The program memory is built from the same state, so compute it
-        // once here and hand it to the builder.
+        // Pass the tracked values so a cached program-memory value that depends on one (e.g. 'h(p)'
+        // after 'p' was reassigned) is re-evaluated rather than served stale. The memory is built
+        // from the same state, so compute it once and hand it to the builder.
         const ProgramState vars = getProgramState();
         ProgramMemory pm = getProgramMemoryFunc(vars);
         if (Token::Match(tok, "&&|%oror%")) {
@@ -743,11 +742,10 @@ struct ValueFlowAnalyzer : Analyzer {
             endBlock = startBlock->link();
         }
 
-        // Pending is set only for the pre-traversal assume; without it the 'then' block has already
-        // been traversed and control is leaving it, so anchor the assumed state at the end of the
-        // block rather than at the condition. Assumptions about variables modified inside the block
-        // (e.g. an 'if' that narrows a value computed in the block) then survive past it, instead of
-        // being discarded because the variable was "modified" since the condition was evaluated.
+        // Without Pending the 'then' block has been traversed and control is leaving it, so anchor
+        // the assumed state at the block end instead of the condition. That keeps assumptions on
+        // variables modified inside the block (e.g. an 'if' narrowing a value computed there) from
+        // being discarded as "modified" once control leaves the block.
         const bool scopeEnd = !(flags & Assume::Pending) && state && endBlock;
         const Token* anchor = scopeEnd ? endBlock : tok;
         const Token* origin = scopeEnd ? endBlock : nullptr;
@@ -757,9 +755,9 @@ struct ValueFlowAnalyzer : Analyzer {
         pms.addState(anchor, getProgramState());
         pms.assume(tok, state, flags & Assume::ContainerEmpty, origin);
 
-        // On the false path the block was already traversed (the true path is handled by scopeEnd
-        // above), so record the assumed state where control continues: past the else block, or past
-        // the closing brace when there is no else, so it is available to the enclosing scope.
+        // The false path (the true path uses scopeEnd above): record the assumed state where control
+        // continues - the end of the else block, or the closing brace when there is no else - so it
+        // reaches the enclosing scope.
         if (isCondBlock && !(flags & Assume::Pending) && !state) {
             if (Token::simpleMatch(endBlock, "} else {"))
                 pms.addState(endBlock->linkAt(2)->previous(), getProgramState());