Flow analysis: clarify when variables are removed from the "promoted" map.

stereotype441 · commit-bot@chromium.org · commit 41907fd4a5b0 · 2019-07-25T15:55:54.000Z
Change-Id: I72fe7d59ccce0dea507af63e1d7910ade8325544 Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/110241 Auto-Submit: Paul Berry <paulberry@google.com> Commit-Queue: Johnni Winther <johnniwinther@google.com> Reviewed-by: Johnni Winther <johnniwinther@google.com>
diff --git a/pkg/front_end/lib/src/fasta/flow_analysis/flow_analysis.dart b/pkg/front_end/lib/src/fasta/flow_analysis/flow_analysis.dart
@@ -718,9 +718,17 @@ class State<Variable, Type> {
 
   /// For each variable whose type is promoted at this point in the control
   /// flow, the promoted type.  Variables whose type is not promoted are not
-  /// present in the map.  Variables that have gone out of scope are not
-  /// guaranteed to be present in the map even if they were promoted at the time
-  /// they went out of scope.
+  /// present in the map.
+  ///
+  /// Flow analysis has no awareness of scope, so variables that are out of
+  /// scope are retained in the map until such time as their promotions would
+  /// have been lost, if their scope had extended to the entire function being
+  /// analyzed.  So, for example, if a variable is declared and then promoted
+  /// inside the `then` branch of an `if` statement, and the `else` branch of
+  /// the `if` statement ends in a `return` statement, then the promotion
+  /// remains in the map after the `if` statement ends.  This should not have
+  /// any effect on analysis results for error-free code, because it is an error
+  /// to refer to a variable that is no longer in scope.
   final Map<Variable, Type> promoted;
 
   /// Creates a state object with the given [reachable] status.  All variables
