Version 3.6.0-28.0.dev

Merge 0c2d58e into dev

pkg/_fe_analyzer_shared/lib/src/flow_analysis/flow_analysis.dart

@@ -654,7 +654,7 @@ abstract class FlowAnalysis<Node extends Object, Statement extends Node,
 
   /// Call this method after visiting the LHS of a logical binary operation
   /// ("||" or "&&").
-  /// [rightOperand] should be the LHS.  [isAnd] should indicate whether the
+  /// [leftOperand] should be the LHS.  [isAnd] should indicate whether the
   /// logical operator is "&&" or "||".  [wholeExpression] should be the whole
   /// logical binary expression.
   void logicalBinaryOp_rightBegin(Expression leftOperand, Node wholeExpression,
@@ -782,10 +782,6 @@ abstract class FlowAnalysis<Node extends Object, Statement extends Node,
   /// out whether the property is promotable.  [unpromotedType] should be the
   /// static type of the value returned by the property get.
   ///
-  /// [isSuperAccess] indicates whether the property in question is being
-  /// accessed through `super.`. If [target] is non-null, the caller should pass
-  /// `false` for [isSuperAccess].
-  ///
   /// Note: although only fields can be promoted, this method uses the
   /// nomenclature "property" rather than "field", to highlight the fact that
   /// it is not necessary for the client to check whether a property refers to a
@@ -1143,9 +1139,8 @@ abstract class FlowAnalysis<Node extends Object, Statement extends Node,
   /// source code (this happens, for example, with compound assignments and with
   /// for-each loops).
   ///
-  /// This should also be used for the implicit write to a non-final variable in
-  /// its initializer, to ensure that the type is promoted to non-nullable if
-  /// necessary; in this case, [viaInitializer] should be `true`.
+  /// This method should not be used for the implicit write to a non-final
+  /// variable in its initializer; in that case, use [initialize] instead.
   void write(Node node, Variable variable, Type writtenType,
       Expression? writtenExpression);
 
@@ -2568,7 +2563,7 @@ class FlowModel<Type extends Object> {
     return new FlowModel<Type>.withInfo(reachable, promotionInfo);
   }
 
-  /// Returns a new [FlowModel] where the information for [reference] is
+  /// Returns a new [FlowModel] where the information for [promotionKey] is
   /// replaced with [model].
   @visibleForTesting
   FlowModel<Type> updatePromotionInfo(FlowModelHelper<Type> helper,
@@ -2580,7 +2575,7 @@ class FlowModel<Type extends Object> {
     return new FlowModel.withInfo(reachable, newPromotionInfo);
   }
 
-  /// Updates the state to indicate that an assignment was made to [variable],
+  /// Updates the state to indicate that an assignment was made to [Variable],
   /// whose key is [variableKey].  The variable is marked as definitely
   /// assigned, and any previous type promotion is removed.
   ///
@@ -2656,7 +2651,7 @@ class FlowModel<Type extends Object> {
   }
 
   /// Forms a new state to reflect a control flow path that might have come from
-  /// either `this` or the [other] state.
+  /// either the [first] or [second] state.
   ///
   /// The control flow path is considered reachable if either of the input
   /// states is reachable.  Variables are considered definitely assigned if they
@@ -2912,10 +2907,9 @@ class PatternVariableInfo<Variable> {
 /// analysis.
 ///
 /// Each instance of [PromotionInfo] is an immutable key/value pair binding a
-/// single promotion [key] (a unique integer assigned by
-/// [_FlowAnalysisImpl._promotionKeyStore] to track a particular promotable
-/// thing) with an instance of [PromotionModel] describing the promotion state
-/// of that thing.
+/// single promotion [key] (a unique integer assigned by [PromotionKeyStore] to
+/// track a particular promotable thing) with an instance of [PromotionModel]
+/// describing the promotion state of that thing.
 ///
 /// Please see the documentation for [FlowLink] for more information about how
 /// this data structure works.
@@ -3022,8 +3016,8 @@ class PromotionModel<Type extends Object> {
   /// Returns a new [PromotionModel] in which any promotions present have been
   /// dropped, and the variable has been marked as "not unassigned".
   ///
-  /// Used by [conservativeJoin] to update the state of variables at the top of
-  /// loops whose bodies write to them.
+  /// Used by [FlowModel.conservativeJoin] to update the state of variables at
+  /// the top of loops whose bodies write to them.
   PromotionModel<Type> discardPromotionsAndMarkNotUnassigned() {
     return new PromotionModel<Type>(
         promotedTypes: null,
@@ -3405,8 +3399,7 @@ class PromotionModel<Type extends Object> {
   /// caveats:
   /// - The "sets" are represented as lists (since they are expected to be very
   ///   small in real-world cases)
-  /// - The sense of equality for the union operation is determined by
-  ///   [FlowAnalysisTypeOperations.isSameType].
+  /// - The sense of equality for the union operation is determined by `==`.
   /// - The types of interests lists are considered immutable.
   static List<Type> joinTested<Type extends Object>(List<Type> types1,
       List<Type> types2, FlowAnalysisTypeOperations<Type> typeOperations) {
@@ -3770,8 +3763,7 @@ class SsaNode<Type extends Object> {
   /// used in a control flow construct.
   ///
   /// We don't bother storing flow analysis information if it's trivial (see
-  /// [_TrivialExpressionInfo]) because such information does not lead to
-  /// promotions.
+  /// [ExpressionInfo]) because such information does not lead to promotions.
   @visibleForTesting
   final ExpressionInfo<Type>? expressionInfo;
 
@@ -4072,8 +4064,8 @@ class TrivialVariableReference<Type extends Object> extends _Reference<Type> {
   /// and `x` has been subsequently written to, then the promotion is
   /// discarded). This is done via [FlowModel.rebaseForward].
   ///
-  /// [current] should be the current flow model, and [typeOperations] should be
-  /// the callback object provided by the client for manipulating types.
+  /// [current] should be the current flow model, and [helper] should be
+  /// the instance of [_FlowAnalysisImpl].
   _Reference<Type> addPreviousInfo(ExpressionInfo<Type>? previousExpressionInfo,
       FlowModelHelper<Type> helper, FlowModel<Type> current) {
     if (previousExpressionInfo != null && previousExpressionInfo.isNonTrivial) {
@@ -4269,8 +4261,8 @@ class _FlowAnalysisImpl<Node extends Object, Statement extends Node,
   /// no such expression has been visited.
   Expression? _expressionWithReference;
 
-  /// If [_expressionVariable] is not `null`, the reference corresponding to it.
-  /// Otherwise `null`.
+  /// If [_expressionWithReference] is not `null`, the reference corresponding
+  /// to it. Otherwise `null`.
   _Reference<Type>? _expressionReference;
 
   final AssignedVariables<Node, Variable> _assignedVariables;
@@ -5598,7 +5590,7 @@ class _FlowAnalysisImpl<Node extends Object, Statement extends Node,
   }
 
   /// Analyzes an equality check between the operands described by
-  /// [leftOperandInfo] and [rightOperandInfo].
+  /// [lhsInfo] and [rhsInfo].
   _EqualityCheckResult _equalityCheck(
       ExpressionInfo<Type> lhsInfo, ExpressionInfo<Type> rhsInfo) {
     TypeClassification leftOperandTypeClassification =
@@ -6016,7 +6008,7 @@ class _FlowAnalysisImpl<Node extends Object, Statement extends Node,
 
   /// Updates the [_stack] to reflect the fact that flow analysis is entering
   /// into a pattern or subpattern match.  [matchedValueInfo] should be the
-  /// [EqualityInfo] representing the value being matched.
+  /// [_Reference] representing the value being matched.
   void _pushPattern(_Reference<Type> matchedValueInfo) {
     _current = _current.split();
     _stack.add(new _TopPatternContext<Type>(matchedValueInfo, _unmatched));
@@ -6032,7 +6024,7 @@ class _FlowAnalysisImpl<Node extends Object, Statement extends Node,
   /// [allowScrutineePromotion] indicates whether pattern matches should cause
   /// the scrutinee to be promoted.
   ///
-  /// The returned value is the [EqualityInfo] representing the value being
+  /// The returned value is the [_Reference] representing the value being
   /// matched.  It should be passed to [_pushPattern].
   _Reference<Type> _pushScrutinee(Expression? scrutinee, Type scrutineeType,
       {required bool allowScrutineePromotion}) {
@@ -6062,7 +6054,7 @@ class _FlowAnalysisImpl<Node extends Object, Statement extends Node,
   }
 
   /// Associates [expression], which should be the most recently visited
-  /// expression, with the given [Reference] object.
+  /// expression, with the given [expressionReference] object.
   void _storeExpressionReference(
       Expression expression, _Reference<Type> expressionReference) {
     _expressionWithReference = expression;
@@ -7068,8 +7060,8 @@ abstract class _PropertyTargetHelper<Expression extends Object,
   /// SSA node representing the implicit variable `this`.
   SsaNode<Type> get _thisSsaNode;
 
-  /// Gets the [Reference] associated with the [expression] (which should be the
-  /// last expression that was traversed).  If there is no [Reference]
+  /// Gets the [_Reference] associated with the [expression] (which should be
+  /// the last expression that was traversed).  If there is no [_Reference]
   /// associated with the [expression], then `null` is returned.
   _Reference<Type>? _getExpressionReference(Expression? expression);
 }
@@ -7188,7 +7180,7 @@ class _SwitchAlternativesContext<Variable extends Object, Type extends Object>
 /// [_FlowContext] representing a switch statement.
 class _SwitchStatementContext<Type extends Object>
     extends _SimpleStatementContext<Type> {
-  /// [EqualityInfo] for the value being matched.
+  /// [_Reference] for the value being matched.
   final _Reference<Type> _matchedValueInfo;
 
   /// Flow state for the code path where no switch cases have matched yet.  If

pkg/_fe_analyzer_shared/lib/src/flow_analysis/flow_analysis_operations.dart

@@ -2,6 +2,10 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
+/// @docImport 'flow_analysis.dart';
+/// @docImport '../field_promotability.dart';
+library;
+
 /// Callback API used by flow analysis to query and manipulate the client's
 /// representation of variables and types.
 abstract interface class FlowAnalysisOperations<Variable extends Object,
@@ -20,9 +24,9 @@ abstract interface class FlowAnalysisOperations<Variable extends Object,
   Type variableType(Variable variable);
 
   /// Returns additional information about why a given property couldn't be
-  /// promoted. [propertyMember] will correspond to a `propertyMember` value
-  /// passed to [FlowAnalysis.promotedPropertyType], [FlowAnalysis.propertyGet],
-  /// or [FlowAnalysis.pushPropertySubpattern].
+  /// promoted. [property] will correspond to a `propertyMember` value passed to
+  /// [FlowAnalysis.promotedPropertyType], [FlowAnalysis.propertyGet], or
+  /// [FlowAnalysis.pushPropertySubpattern].
   ///
   /// This method is only called if a closure returned by
   /// [FlowAnalysis.whyNotPromoted] is invoked, and the expression being queried

pkg/_fe_analyzer_shared/lib/src/type_inference/assigned_variables.dart

@@ -19,7 +19,9 @@ import 'promotion_key_store.dart';
 /// flow analysis.
 ///
 /// Then, in the second phase, the client may make queries using
-/// [capturedAnywhere], [writtenInNode], and [capturedInNode].
+/// [AssignedVariablesForTesting.capturedAnywhere],
+/// [AssignedVariablesForTesting.writtenInNode], and
+/// [AssignedVariablesForTesting.capturedInNode].
 ///
 /// We use the term "node" to refer generally to a loop statement, switch
 /// statement, try statement, loop collection element, local function, or
@@ -39,7 +41,7 @@ class AssignedVariables<Node extends Object, Variable extends Object> {
   ];
 
   /// When assertions are enabled, the set of info objects that have been
-  /// retrieved by [deferNode] but not yet sent to [storeNode].
+  /// retrieved by [deferNode] but not yet sent to [storeInfo].
   final Set<AssignedVariablesNodeInfo> _deferredInfos =
       new Set<AssignedVariablesNodeInfo>.identity();
 
@@ -100,7 +102,7 @@ class AssignedVariables<Node extends Object, Variable extends Object> {
   ///
   /// In contrast to [endNode], this method doesn't store the data gathered for
   /// the node for later use; instead it returns it to the caller.  At a later
-  /// time, the caller should pass the returned data to [storeNodeInfo].
+  /// time, the caller should pass the returned data to [storeInfo].
   ///
   /// See [beginNode] for more details.
   AssignedVariablesNodeInfo deferNode(

pkg/_fe_analyzer_shared/lib/src/type_inference/type_analysis_result.dart

@@ -250,9 +250,8 @@ class MatchContext<Node extends Object, Expression extends Node,
         unnecessaryWildcardKind: unnecessaryWildcardKind,
       );
 
-  /// Returns a modified version of `this`, with both [initializer] and
-  /// [switchScrutinee] set to `null` (because this context is not for a
-  /// top-level pattern anymore).
+  /// Returns a modified version of `this`, with [switchScrutinee] set to `null`
+  /// (because this context is not for a top-level pattern anymore).
   MatchContext<Node, Expression, Pattern, Type, Variable>
       withUnnecessaryWildcardKind(
           UnnecessaryWildcardKind? unnecessaryWildcardKind) {

pkg/_fe_analyzer_shared/lib/src/type_inference/type_analyzer.dart

@@ -148,7 +148,7 @@ class RelationalOperatorResolution<Type extends SharedType> {
 /// The client is free to `implement` or `extend` this class.
 class SwitchExpressionMemberInfo<Node extends Object, Expression extends Node,
     Variable extends Object> {
-  /// The [CaseOrDefaultHead] associated with this clause.
+  /// The [CaseHeadOrDefaultInfo] associated with this clause.
   final CaseHeadOrDefaultInfo<Node, Expression, Variable> head;
 
   /// The body of the `case` or `default` clause.
@@ -1229,9 +1229,7 @@ mixin TypeAnalyzer<
   }
 
   /// Analyzes an object pattern.  [node] is the pattern itself, and [fields]
-  /// is the list of subpatterns.  The [requiredType] must be not `null` in
-  /// irrefutable contexts, but can be `null` in refutable contexts, then
-  /// [downwardInferObjectPatternRequiredType] is invoked to infer the type.
+  /// is the list of subpatterns.
   ///
   /// Returns a [ObjectPatternResult] with the required type and information
   /// about reported errors.
@@ -1437,13 +1435,8 @@ mixin TypeAnalyzer<
   /// `var pattern = initializer` or `final pattern = initializer`.
   ///
   /// [node] should be the AST node for the entire declaration, [pattern] for
-  /// the pattern, and [initializer] for the initializer.  [isFinal] and
-  /// [isLate] indicate whether this is a final declaration and/or a late
-  /// declaration, respectively.
-  ///
-  /// Note that the only kind of pattern allowed in a late declaration is a
-  /// variable pattern; [TypeAnalyzerErrors.patternDoesNotAllowLate] will be
-  /// reported if any other kind of pattern is used.
+  /// the pattern, and [initializer] for the initializer.  [isFinal] indicates
+  /// whether this is a final declaration.
   ///
   /// Returns a [PatternVariableDeclarationAnalysisResult] holding the static
   /// type of the initializer and the type schema of the [pattern].
@@ -1972,9 +1965,8 @@ mixin TypeAnalyzer<
   /// `var variable;`.
   ///
   /// [node] should be the AST node for the entire declaration, [variable] for
-  /// the variable, and [declaredType] for the type (if present).  [isFinal] and
-  /// [isLate] indicate whether this is a final declaration and/or a late
-  /// declaration, respectively.
+  /// the variable, and [declaredType] for the type (if present).  [isFinal]
+  /// indicates whether this is a final declaration.
   ///
   /// Stack effect: none.
   ///
@@ -1990,7 +1982,7 @@ mixin TypeAnalyzer<
 
   /// Analyzes a wildcard pattern.  [node] is the pattern.
   ///
-  /// Returns a [WildcardPattern] with information about reported errors.
+  /// Returns a [WildcardPatternResult] with information about reported errors.
   ///
   /// See [dispatchPattern] for the meaning of [context].
   ///
@@ -2062,8 +2054,8 @@ mixin TypeAnalyzer<
   /// [node], and then adjusts the stack as needed to combine any
   /// sub-structures into a single expression.
   ///
-  /// For example, if [node] is a binary expression (`a + b`), calls
-  /// [analyzeBinaryExpression].
+  /// For example, if [node] is a switch expression, calls
+  /// [analyzeSwitchExpression].
   ///
   /// Stack effect: pushes (Expression).
   ExpressionTypeAnalysisResult<Type> dispatchExpression(
@@ -2090,7 +2082,8 @@ mixin TypeAnalyzer<
   /// [statement], and then adjusts the stack as needed to combine any
   /// sub-structures into a single statement.
   ///
-  /// For example, if [statement] is a `while` loop, calls [analyzeWhileLoop].
+  /// For example, if [statement] is a switch statement, calls
+  /// [analyzeSwitchStatement].
   ///
   /// Stack effect: pushes (Statement).
   void dispatchStatement(Statement statement);
@@ -2123,23 +2116,23 @@ mixin TypeAnalyzer<
   /// If [node] is [isRestPatternElement], returns its optional pattern.
   Pattern? getRestPatternElementPattern(Node node);
 
-  /// Returns an [ExpressionCaseInfo] object describing the [index]th `case` or
-  /// `default` clause in the switch expression [node].
+  /// Returns an [SwitchExpressionMemberInfo] object describing the [index]th
+  /// `case` or `default` clause in the switch expression [node].
   ///
   /// Note: it is allowed for the client's AST nodes for `case` and `default`
-  /// clauses to implement [ExpressionCaseInfo], in which case this method can
-  /// simply return the [index]th `case` or `default` clause.
+  /// clauses to implement [SwitchExpressionMemberInfo], in which case this
+  /// method can simply return the [index]th `case` or `default` clause.
   ///
   /// See [analyzeSwitchExpression].
   SwitchExpressionMemberInfo<Node, Expression, Variable>
       getSwitchExpressionMemberInfo(Expression node, int index);
 
-  /// Returns a [StatementCaseInfo] object describing the [index]th `case` or
-  /// `default` clause in the switch statement [node].
+  /// Returns a [SwitchStatementMemberInfo] object describing the [caseIndex]th
+  /// `case` or `default` clause in the switch statement [node].
   ///
   /// Note: it is allowed for the client's AST nodes for `case` and `default`
-  /// clauses to implement [StatementCaseInfo], in which case this method can
-  /// simply return the [index]th `case` or `default` clause.
+  /// clauses to implement [SwitchStatementMemberInfo], in which case this
+  /// method can simply return the [caseIndex]th `case` or `default` clause.
   ///
   /// See [analyzeSwitchStatement].
   SwitchStatementMemberInfo<Node, Statement, Expression, Variable>

pkg/_fe_analyzer_shared/lib/src/type_inference/type_analyzer_operations.dart

@@ -113,7 +113,7 @@ abstract interface class TypeAnalyzerOperations<
   bool isNonNullable(TypeSchema typeSchema);
 
   /// Returns `true` if [type] is `Null`.
-  bool isNull(Type Type);
+  bool isNull(Type type);
 
   /// Returns `true` if [type] is `Object` from `dart:core`. The method returns
   /// `false` for `Object?` and `Object*`.
@@ -155,7 +155,7 @@ abstract interface class TypeAnalyzerOperations<
   });
 
   /// Returns the type schema `Map`, with type arguments [keyTypeSchema] and
-  /// [elementTypeSchema].
+  /// [valueTypeSchema].
   TypeSchema mapTypeSchema(
       {required TypeSchema keyTypeSchema, required TypeSchema valueTypeSchema});
 

pkg/_fe_analyzer_shared/lib/src/type_inference/type_constraint.dart

@@ -269,7 +269,7 @@ class TypeConstraintFromExtendsClause<
   /// Name of the type parameter with the extends clause.
   final String typeParameterName;
 
-  /// The declared bound of [typeParam], not `null`, because we create
+  /// The declared bound of the type parameter, not `null`, because we create
   /// this clause only when it is not `null`.
   ///
   /// For example `Iterable<T>` for `<T, E extends Iterable<T>>`.