Fix comment references in type_inference and mini_*.dart.
Fix bracketed references in doc comments that previously pointed to
nowhere, in the following source code:
- Shared type inference logic
(pkg/_fe_analyzer_shared/lib/src/type_inference/...).
- Testing infrastructure that exercises shared type inference logic
and flow analysis (pkg/_fe_analyzer_shared/test/mini_*.dart).
This is part of a larger effort to clean up _fe_analyzer_shared to the
point where the `comment_references` lint can be enabled.
Change-Id: I15e6133dc7631c9a634131f0df3a3ff14f568e3b
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/375201
Reviewed-by: Konstantin Shcheglov <scheglov@google.com>
Commit-Queue: Paul Berry <paulberry@google.com>
diff --git a/pkg/_fe_analyzer_shared/lib/src/type_inference/assigned_variables.dart b/pkg/_fe_analyzer_shared/lib/src/type_inference/assigned_variables.dart
index 5338558..8137afb 100644
--- a/pkg/_fe_analyzer_shared/lib/src/type_inference/assigned_variables.dart
+++ b/pkg/_fe_analyzer_shared/lib/src/type_inference/assigned_variables.dart
@@ -19,7 +19,9 @@
/// 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 @@
];
/// 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 @@
///
/// 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(
diff --git a/pkg/_fe_analyzer_shared/lib/src/type_inference/type_analysis_result.dart b/pkg/_fe_analyzer_shared/lib/src/type_inference/type_analysis_result.dart
index 54ee8f3..0c1030b 100644
--- a/pkg/_fe_analyzer_shared/lib/src/type_inference/type_analysis_result.dart
+++ b/pkg/_fe_analyzer_shared/lib/src/type_inference/type_analysis_result.dart
@@ -250,9 +250,8 @@
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) {
diff --git a/pkg/_fe_analyzer_shared/lib/src/type_inference/type_analyzer.dart b/pkg/_fe_analyzer_shared/lib/src/type_inference/type_analyzer.dart
index d843002..90d6818 100644
--- a/pkg/_fe_analyzer_shared/lib/src/type_inference/type_analyzer.dart
+++ b/pkg/_fe_analyzer_shared/lib/src/type_inference/type_analyzer.dart
@@ -148,7 +148,7 @@
/// 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 @@
}
/// 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 @@
/// `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 @@
/// `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 @@
/// 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 @@
/// [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 @@
/// [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 @@
/// 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>
diff --git a/pkg/_fe_analyzer_shared/lib/src/type_inference/type_analyzer_operations.dart b/pkg/_fe_analyzer_shared/lib/src/type_inference/type_analyzer_operations.dart
index b30c1ba..0ef0c31 100644
--- a/pkg/_fe_analyzer_shared/lib/src/type_inference/type_analyzer_operations.dart
+++ b/pkg/_fe_analyzer_shared/lib/src/type_inference/type_analyzer_operations.dart
@@ -113,7 +113,7 @@
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 @@
});
/// Returns the type schema `Map`, with type arguments [keyTypeSchema] and
- /// [elementTypeSchema].
+ /// [valueTypeSchema].
TypeSchema mapTypeSchema(
{required TypeSchema keyTypeSchema, required TypeSchema valueTypeSchema});
diff --git a/pkg/_fe_analyzer_shared/lib/src/type_inference/type_constraint.dart b/pkg/_fe_analyzer_shared/lib/src/type_inference/type_constraint.dart
index 12b3db3..4a1c0e4 100644
--- a/pkg/_fe_analyzer_shared/lib/src/type_inference/type_constraint.dart
+++ b/pkg/_fe_analyzer_shared/lib/src/type_inference/type_constraint.dart
@@ -269,7 +269,7 @@
/// 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>>`.
diff --git a/pkg/_fe_analyzer_shared/test/mini_ast.dart b/pkg/_fe_analyzer_shared/test/mini_ast.dart
index 6f150ff..daacb3c 100644
--- a/pkg/_fe_analyzer_shared/test/mini_ast.dart
+++ b/pkg/_fe_analyzer_shared/test/mini_ast.dart
@@ -155,7 +155,7 @@
/// Creates a conventional `for` statement. Optional boolean [forCollection]
/// indicates that this `for` statement is actually a collection element, so
-/// `null` should be passed to [for_bodyBegin].
+/// `null` should be passed to [FlowAnalysis.for_bodyBegin].
Statement for_(ProtoStatement? initializer, ProtoExpression? condition,
ProtoExpression? updater, List<ProtoStatement> body,
{bool forCollection = false}) {
@@ -428,7 +428,7 @@
return result;
}
-/// Creates a "rest" pattern with optional [subPatern], for use in a list
+/// Creates a "rest" pattern with optional [subPattern], for use in a list
/// pattern.
///
/// Although using a rest pattern inside a map pattern is an error, it's allowed
@@ -834,7 +834,7 @@
}
/// Representation of a single catch clause in a try/catch statement. Use
-/// [catch_] to create instances of this class.
+/// [TryBuilder.catch_] to create instances of this class.
class CatchClause {
final Statement body;
final Var? exception;
@@ -1386,7 +1386,8 @@
}
/// Representation of a single case clause in a switch expression. Use
-/// [caseExpr] to create instances of this class.
+/// [PossiblyGuardedPattern.thenExpr] or [SwitchHead.thenExpr] to create
+/// instances of this class.
class ExpressionCase extends Node {
final GuardedPattern? guardedPattern;
final Expression expression;
@@ -1680,7 +1681,8 @@
_thisType = Type(type);
}
- /// Updates the harness with a new result for [downwardInfer].
+ /// Updates the harness with a new result for
+ /// [MiniAstOperations.downwardInfer].
void addDownwardInfer({
required String name,
required String context,
@@ -1693,8 +1695,9 @@
);
}
- /// Updates the harness so that when an [isAlwaysExhaustiveType] query is
- /// invoked on type [type], [isExhaustive] will be returned.
+ /// Updates the harness so that when an
+ /// [TypeAnalyzerOperations.isAlwaysExhaustiveType] query is invoked on type
+ /// [type], [isExhaustive] will be returned.
void addExhaustiveness(String type, bool isExhaustive) {
operations.addExhaustiveness(type, isExhaustive);
}
@@ -2757,8 +2760,8 @@
_downwardInferenceResults[query] = Type(result);
}
- /// Updates the harness so that when an [isExhaustiveType] query is invoked on
- /// type [type], [isExhaustive] will be returned.
+ /// Updates the harness so that when an [isAlwaysExhaustiveType] query is
+ /// invoked on type [type], [isExhaustive] will be returned.
void addExhaustiveness(String type, bool isExhaustive) {
_exhaustiveness[type] = isExhaustive;
}
@@ -4119,7 +4122,7 @@
/// expression statement.
///
/// In general, tests shouldn't need to call this method directly; instead
- /// they should simply be able to use either a [Statement] or an [Expressions]
+ /// they should simply be able to use either a [Statement] or an [Expression]
/// in a context where a statement is expected, and the test infrastructure
/// will call this getter as needed.
Statement asStatement({required String location});
@@ -4492,8 +4495,9 @@
}
}
-/// Representation of a single case clause in a switch statement. Use [case_]
-/// to create instances of this class.
+/// Representation of a single case clause in a switch statement. Use
+/// [PossiblyGuardedPattern.then] or [SwitchHead.then] to create instances of
+/// this class.
class SwitchStatementMember extends Node {
final bool hasLabels;
final List<SwitchHead> elements;
diff --git a/pkg/_fe_analyzer_shared/test/mini_ir.dart b/pkg/_fe_analyzer_shared/test/mini_ir.dart
index 9ffa1ad..9862909 100644
--- a/pkg/_fe_analyzer_shared/test/mini_ir.dart
+++ b/pkg/_fe_analyzer_shared/test/mini_ir.dart
@@ -113,9 +113,10 @@
return MiniIRTmp._('t${_tmpCounter++}', _pop(Kind.expression).ir);
}
- /// Pops the top [numArgs] nodes from the stack and pushes a node that
- /// combines them using [name]. For example, if the stack contains `1, 2, 3`,
- /// calling `apply('f', 2)` results in a stack of `1, f(2, 3)`.
+ /// Pops the top [inputKinds].length nodes from the stack and pushes a node
+ /// that combines them using [name]. For example, if the stack contains
+ /// `1, 2, 3`, calling `apply('f', [Kind.expression, Kind.expression])`
+ /// results in a stack of `1, f(2, 3)`.
///
/// Optional argument [names] allows applying names to the last n arguments.
/// For example, if the stack contains `1, 2, 3`, calling
diff --git a/pkg/_fe_analyzer_shared/test/mini_types.dart b/pkg/_fe_analyzer_shared/test/mini_types.dart
index f0a4c44..5a7ac29 100644
--- a/pkg/_fe_analyzer_shared/test/mini_types.dart
+++ b/pkg/_fe_analyzer_shared/test/mini_types.dart
@@ -383,15 +383,6 @@
/// Representation of a type suitable for unit testing of code in the
/// `_fe_analyzer_shared` package.
-///
-/// Note that we don't want code in `_fe_analyzer_shared` to inadvertently
-/// compare types using `==` (or to store types in sets/maps, which can trigger
-/// `==` to be used to compare them); this could cause bugs by causing
-/// alternative spellings of the same type to be treated differently (e.g.
-/// `FutureOr<int?>?` should be treated equivalently to `FutureOr<int?>`). To
-/// help ensure this, both `==` and `hashCode` throw exceptions by default. To
-/// defeat this behavior (e.g. so that a type can be passed to `expect`, use
-/// [Type.withComparisonsAllowed].
abstract class Type implements SharedType {
@override
final NullabilitySuffix nullabilitySuffix;
