analyzer: Correct 40 comment references

There are fewer than 140 `comment_references` violations after this
change.

Change-Id: I1d19db7e293b43400a6e076945d84f509862f873
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/392501
Reviewed-by: Konstantin Shcheglov <[email protected]>
Commit-Queue: Samuel Rawlins <[email protected]>

Author: srawlins

pkg/analyzer/lib/src/dart/ast/ast.dart

@@ -3222,8 +3222,6 @@ final class CommentImpl extends AstNodeImpl
   ///
   /// The list of [tokens] must contain at least one token.
   ///
-  /// The [type] is the type of the comment.
-  ///
   /// The list of [references] can be empty if the comment doesn't contain any
   /// embedded references.
   CommentImpl({
@@ -4078,7 +4076,7 @@ abstract final class ConstructorDeclaration
   @override
   ConstructorFragment? get declaredFragment;
 
-  /// The token for the `external` keyword to the given [token].
+  /// The token for the `external` keyword to this constructor declaration.
   Token? get externalKeyword;
 
   /// The token for the `factory` keyword, or `null` if the constructor isn't a
@@ -4774,7 +4772,7 @@ sealed class DartPatternImpl extends AstNodeImpl
 
   DartType computePatternSchema(ResolverVisitor resolverVisitor);
 
-  /// Dispatches this pattern to the [resolver], with the given [context]
+  /// Dispatches this pattern to the [resolverVisitor], with the given [context]
   /// information.
   ///
   /// Note: most code shouldn't call this method directly, but should instead
@@ -7144,8 +7142,6 @@ sealed class ForEachPartsImpl extends ForLoopPartsImpl implements ForEachParts {
 
   /// Initializes a newly created for-each statement whose loop control variable
   /// is declared internally (in the for-loop part).
-  ///
-  /// The [awaitKeyword] can be `null` if this isn't an asynchronous for loop.
   ForEachPartsImpl({
     required this.inKeyword,
     required ExpressionImpl iterable,
@@ -7768,8 +7764,6 @@ sealed class ForPartsImpl extends ForLoopPartsImpl implements ForParts {
 
   /// Initializes a newly created for statement.
   ///
-  /// Either the [variableList] or the [initialization] must be `null`.
-  ///
   /// Either the [condition] and the list of [updaters] can be `null` if the
   /// loop doesn't have the corresponding attribute.
   ForPartsImpl({
@@ -10710,10 +10704,12 @@ abstract final class InvocationExpression implements Expression {
   ///
   /// For example:
   ///
-  ///     (o.m)<TArgs>(args); // target is `o.m`
-  ///     o.m<TArgs>(args);   // target is `m`
+  /// ```dart
+  /// (o.m)<TArgs>(args); // target is `o.m`
+  /// o.m<TArgs>(args);   // target is `m`
+  /// ```
   ///
-  /// In either case, the [function.staticType] is the [staticInvokeType] before
+  /// In either case, the `function.staticType` is the [staticInvokeType] before
   /// applying type arguments `TArgs`.
   Expression get function;
 
@@ -15678,11 +15674,10 @@ final class SetOrMapLiteralImpl extends TypedLiteralImpl
   /// whether the kind hasn't or can't be determined.
   _SetOrMapKind _resolvedKind = _SetOrMapKind.unresolved;
 
-  /// The context type computed by
-  /// [ResolverVisitor._computeSetOrMapContextType].
+  /// The context type computed by [TypedLiteralResolver].
   ///
   /// Note that this isn't the same as the context pushed down by type
-  /// inference (which can be obtained via [InferenceContext.getContext]). For
+  /// inference (which can be obtained via `InferenceContext.getContext`). For
   /// example, in the following code:
   ///
   ///     var m = {};
@@ -16828,9 +16823,6 @@ final class SuperFormalParameterImpl extends NormalFormalParameterImpl
   ///
   /// The [type] must be `null` if the keyword is `var`.
   ///
-  /// The [thisKeyword] and [period] can be `null` if the keyword `this` isn't
-  /// provided.
-  ///
   /// The[parameters] can be `null` if this isn't a function-typed field formal
   /// parameter.
   SuperFormalParameterImpl({
@@ -18304,7 +18296,7 @@ sealed class UriBasedDirectiveImpl extends DirectiveImpl
   }
 }
 
-/// Validation codes returned by [UriBasedDirective.validate].
+/// Validation codes returned by [UriBasedDirectiveImpl.validateUri].
 class UriValidationCode {
   static const UriValidationCode INVALID_URI = UriValidationCode('INVALID_URI');
 
@@ -18717,7 +18709,7 @@ sealed class VariablePatternImpl extends DartPatternImpl
 ///    switchCase ::=
 ///        'when' [Expression]
 abstract final class WhenClause implements AstNode {
-  /// The condition that is evaluated when the [pattern] matches, that must
+  /// The condition that is evaluated when the pattern matches, that must
   /// evaluate to `true` in order for the [expression] to be executed.
   Expression get expression;
 

pkg/analyzer/lib/src/dart/constant/evaluation.dart

@@ -331,7 +331,7 @@ class ConstantEvaluationEngine {
     }
   }
 
-  /// Evaluate the constructor call and format any [InvalidConstants] if found.
+  /// Evaluates the constructor call and format any [InvalidConstant]s if found.
   Constant evaluateAndFormatErrorsInConstructorCall(
     LibraryElementImpl library,
     AstNode node,
@@ -545,12 +545,11 @@ class ConstantVisitor extends UnifyingAstVisitor<Constant> {
   /// Helper class used to compute constant values.
   late final DartObjectComputer _dartObjectComputer;
 
-  /// Initialize a newly created constant visitor. The [evaluationEngine] is
+  /// Initializes a newly created constant visitor. The [_evaluationEngine] is
   /// used to evaluate instance creation expressions. The [lexicalEnvironment]
   /// is a map containing values which should override identifiers, or `null` if
   /// no overriding is necessary. The [_errorReporter] is used to report errors
-  /// found during evaluation.  The [validator] is used by unit tests to verify
-  /// correct dependency analysis.
+  /// found during evaluation.
   ///
   /// The [substitution] is specified for instance creations.
   ConstantVisitor(
@@ -569,11 +568,10 @@ class ConstantVisitor extends UnifyingAstVisitor<Constant> {
     );
   }
 
-  /// Convenience getter to gain access to the [evaluationEngine]'s type system.
+  /// Convenience getter to access the [_evaluationEngine]'s type system.
   TypeSystemImpl get typeSystem => _library.typeSystem;
 
-  /// Convenience getter to gain access to the [evaluationEngine]'s type
-  /// provider.
+  /// Convenience getter to access the [_evaluationEngine]'s type provider.
   TypeProvider get _typeProvider => _library.typeProvider;
 
   /// Evaluates and reports an error if the evaluation result of [node] is an
@@ -2417,9 +2415,9 @@ class _InstanceCreationEvaluator {
   /// An error reporter for errors determined while computing values for field
   /// initializers, or default values for the constructor parameters.
   ///
-  /// Such errors cannot be reported into [_errorReporter], because they usually
-  /// happen in a different source. But they still should cause a constant
-  /// evaluation error for the current node.
+  /// Such errors cannot be reported into [ConstantVisitor._errorReporter],
+  /// because they usually happen in a different source. But they still should
+  /// cause a constant evaluation error for the current node.
   late final ErrorReporter _externalErrorReporter = ErrorReporter(
     _externalErrorListener,
     _constructor.source,
@@ -2650,14 +2648,12 @@ class _InstanceCreationEvaluator {
     return null;
   }
 
-  /// Check that the arguments to a call to `fromEnvironment()` are correct.
+  /// Checks that the arguments to a call to `fromEnvironment()` are correct.
   ///
-  /// The [arguments] are the AST nodes of the arguments. The [argumentValues]
-  /// are the values of the unnamed arguments. The [namedArgumentValues] are the
-  /// values of the named arguments. The [expectedDefaultValueType] is the
-  /// allowed type of the "defaultValue" parameter (if present). Note:
-  /// "defaultValue" is always allowed to be `null`. Return `true` if the
-  /// arguments are correct, `false` otherwise.
+  /// The [arguments] are the AST nodes of the arguments. The
+  /// [expectedDefaultValueType] is the allowed type of the "defaultValue"
+  /// parameter (if present). Note: "defaultValue" is always allowed to be
+  /// `null`. Returns `true` if the arguments are correct, `false` otherwise.
   bool _checkFromEnvironmentArguments(
     List<Expression> arguments,
     InterfaceType expectedDefaultValueType,
@@ -3013,10 +3009,8 @@ class _InstanceCreationEvaluator {
 
   /// Checks that the arguments to a call to [Symbol.new] are correct.
   ///
-  /// The [arguments] are the AST nodes of the arguments. The [argumentValues]
-  /// are the values of the unnamed arguments. The [namedArgumentValues] are the
-  /// values of the named arguments. Returns `true` if the arguments are
-  /// correct, `false` otherwise.
+  /// The [arguments] are the AST nodes of the arguments. Returns `true` if the
+  /// arguments are correct, `false` otherwise.
   bool _checkSymbolArguments(List<Expression> arguments) {
     if (arguments.length != 1) {
       return false;

pkg/analyzer/lib/src/dart/constant/value.dart

@@ -3,6 +3,8 @@
 // BSD-style license that can be found in the LICENSE file.
 
 /// The implementation of the class [DartObject].
+///
+/// @docImport 'package:analyzer/src/dart/constant/evaluation.dart';
 library;
 
 import 'dart:collection';
@@ -627,8 +629,8 @@ class DartObjectImpl implements DartObject, Constant {
     );
   }
 
-  /// Return the result of invoking the '&&' operator on this object with the
-  /// [rightOperand].
+  /// Returns the result of invoking the '&&' operator on this object with the
+  /// [rightOperandComputer].
   ///
   /// Throws an [EvaluationException] if the operator is not appropriate for an
   /// object of this kind.
@@ -641,8 +643,8 @@ class DartObjectImpl implements DartObject, Constant {
     );
   }
 
-  /// Return the result of invoking the '||' operator on this object with the
-  /// [rightOperand].
+  /// Returns the result of invoking the '||' operator on this object with the
+  /// [rightOperandComputer].
   ///
   /// Throws an [EvaluationException] if the operator is not appropriate for an
   /// object of this kind.
@@ -1754,8 +1756,8 @@ abstract class InstanceState {
   /// the [rightOperand].
   BoolState isIdentical(TypeSystemImpl typeSystem, InstanceState rightOperand);
 
-  /// Return the result of invoking the '&&' operator on this object with the
-  /// [rightOperand].
+  /// Returns the result of invoking the '&&' operator on this object with the
+  /// [rightOperandComputer].
   ///
   /// Throws an [EvaluationException] if the operator is not appropriate for an
   /// object of this kind.
@@ -1769,8 +1771,8 @@ abstract class InstanceState {
     return rightOperand!.convertToBool();
   }
 
-  /// Return the result of invoking the '||' operator on this object with the
-  /// [rightOperand].
+  /// Returns the result of invoking the '||' operator on this object with the
+  /// [rightOperandComputer].
   ///
   /// Throws an [EvaluationException] if the operator is not appropriate for an
   /// object of this kind.

pkg/analyzer/lib/src/dart/element/element.dart

@@ -3638,7 +3638,7 @@ class ExtensionElementImpl extends InstanceElementImpl
   late MaybeAugmentedExtensionElementMixin augmentedInternal;
 
   /// Initialize a newly created extension element to have the given [name] at
-  /// the given [offset] in the file that contains the declaration of this
+  /// the given [nameOffset] in the file that contains the declaration of this
   /// element.
   ExtensionElementImpl(super.name, super.nameOffset);
 
@@ -5675,7 +5675,7 @@ class LabelElementImpl extends ElementImpl implements LabelElement {
   final bool _onSwitchMember;
 
   /// Initialize a newly created label element to have the given [name].
-  /// [onSwitchMember] should be `true` if this label is associated with a
+  /// [_onSwitchMember] should be `true` if this label is associated with a
   /// `switch` member.
   LabelElementImpl(String super.name, super.nameOffset, this._onSwitchMember);
 
@@ -9940,8 +9940,8 @@ class TypeAliasElementImpl extends _ExistingElementImpl
   LibraryFragment? get enclosingFragment =>
       enclosingElement3 as LibraryFragment;
 
-  /// Returns whether this alias is a "proper rename" of [aliasedClass], as
-  /// defined in the constructor-tearoffs specification.
+  /// Whether this alias is a "proper rename" of [aliasedType], as defined in
+  /// the constructor-tearoffs specification.
   bool get isProperRename {
     var aliasedType_ = aliasedType;
     if (aliasedType_ is! InterfaceType) {
@@ -10212,7 +10212,7 @@ class TypeParameterElementImpl extends ElementImpl
   TypeParameterElementImpl(String super.name, super.offset);
 
   /// Initialize a newly created synthetic type parameter element to have the
-  /// given [name], and with [synthetic] set to true.
+  /// given [name], and with [isSynthetic] set to `true`.
   TypeParameterElementImpl.synthetic(String name) : super(name, -1) {
     isSynthetic = true;
   }
@@ -10325,7 +10325,7 @@ class TypeParameterElementImpl extends ElementImpl
     builder.writeTypeParameter(this);
   }
 
-  /// Computes the variance of the [typeParameter] in the [type].
+  /// Computes the variance of the type parameters in the [type].
   shared.Variance computeVarianceInType(DartType type) {
     if (type is TypeParameterType) {
       if (type.element == this) {

pkg/analyzer/lib/src/dart/element/generic_inferrer.dart

@@ -36,9 +36,9 @@ import 'package:collection/collection.dart';
 
 /// Tracks upper and lower type bounds for a set of type parameters.
 ///
-/// This class is used by calling [isSubtypeOf]. When it encounters one of
-/// the type parameters it is inferring, it will record the constraint, and
-/// optimistically assume the constraint will be satisfied.
+/// When the methods of this class encounter one of the type parameters it is
+/// inferring, it will record the constraint, and optimistically assume the
+/// constraint will be satisfied.
 ///
 /// For example if we are inferring type parameter A, and we ask if
 /// `A <: num`, this will record that A must be a subtype of `num`. It also
@@ -47,7 +47,7 @@ import 'package:collection/collection.dart';
 /// (due to covariant generic types) as would `() -> A <: () -> num`. In
 /// contrast `(A) -> void <: (num) -> void`.
 ///
-/// Once the lower/upper bounds are determined, [infer] should be called to
+/// Once the lower/upper bounds are determined, `infer` should be called to
 /// finish the inference. It will instantiate a generic function type with the
 /// inferred types for each type parameter.
 ///
@@ -154,8 +154,8 @@ class GenericInferrer {
     return types;
   }
 
-  /// Apply an argument constraint, which asserts that the [argument] staticType
-  /// is a subtype of the [parameterType].
+  /// Apply an argument constraint, which asserts that the [argumentType] static
+  /// type is a subtype of the [parameterType].
   void constrainArgument(
       DartType argumentType, DartType parameterType, String parameterName,
       {InterfaceElement? genericClass, required AstNode? nodeForTesting}) {
@@ -386,7 +386,7 @@ class GenericInferrer {
     return result;
   }
 
-  /// Check that inferred [typeArguments] satisfy the [typeParameters] bounds.
+  /// Check that inferred [typeArguments] satisfy the [_typeParameters] bounds.
   void _checkArgumentsNotMatchingBounds({
     required SyntacticEntity? errorEntity,
     required ErrorReporter? errorReporter,
@@ -490,7 +490,7 @@ class GenericInferrer {
     }
   }
 
-  /// Computes (or recomputes) a set of [inferredTypes] based on the constraints
+  /// Computes (or recomputes) a set of inferred types based on the constraints
   /// that have been recorded so far.
   List<DartType> _chooseTypes({required bool preliminary}) {
     var inferredTypes = List<DartType>.filled(
@@ -873,11 +873,11 @@ class GenericInferrer {
     }
   }
 
-  /// Tries to make [i1] a subtype of [i2] and accumulate constraints as needed.
+  /// Tries to make [t1] a subtype of [t2] and accumulate constraints as needed.
   ///
   /// The return value indicates whether the match was successful.  If it was
   /// unsuccessful, any constraints that were accumulated during the match
-  /// attempt have been rewound (see [_rewindConstraints]).
+  /// attempt have been rewound.
   bool _tryMatchSubtypeOf(
       DartType t1,
       DartType t2,

pkg/analyzer/lib/src/dart/element/least_upper_bound.dart

@@ -196,11 +196,11 @@ class InterfaceLeastUpperBoundHelper {
     return NullabilitySuffix.none;
   }
 
-  /// Return the length of the longest inheritance path from a subtype of the
-  /// given [element] to Object, where the given [depth] is the length of the
-  /// longest path from the subtype to this type. The set of [visitedElements]
-  /// is used to prevent infinite recursion in the case of a cyclic type
-  /// structure.
+  /// Returns the length of the longest inheritance path from a subtype of the
+  /// given [type] to `Object`.
+  ///
+  /// The set of [visitedElements] is used to prevent infinite recursion in the
+  /// case of a cyclic type structure.
   static int _computeLongestInheritancePathToObject(
       InterfaceType type, Set<InterfaceElement> visitedElements) {
     var element = type.element;

pkg/analyzer/lib/src/dart/element/type_constraint_gatherer.dart

@@ -20,8 +20,8 @@ import 'package:analyzer/src/dart/element/type_schema.dart';
 import 'package:analyzer/src/dart/element/type_system.dart';
 import 'package:analyzer/src/dart/resolver/flow_analysis_visitor.dart';
 
-/// Creates sets of [TypeConstraint]s for type parameters, based on an attempt
-/// to make one type schema a subtype of another.
+/// Creates sets of [GeneratedTypeConstraint]s for type parameters, based on an
+/// attempt to make one type schema a subtype of another.
 class TypeConstraintGatherer extends shared.TypeConstraintGenerator<
         DartType,
         ParameterElement,

pkg/analyzer/lib/src/dart/micro/utils.dart

@@ -62,9 +62,9 @@ ConstructorElement? _getActualConstructorElement(
   return constructor;
 }
 
-/// Return the [LibraryImportElement] that declared [prefix] and imports [element].
+/// Returns the [LibraryImportElement] that declared [prefix] and imports [element].
 ///
-/// [libraryElement] - the [LibraryElement] where reference is.
+/// [libraryFragment] - the [CompilationUnitElementImpl] where reference is.
 /// [prefix] - the import prefix, maybe `null`.
 /// [element] - the referenced element.
 /// [importElementsMap] - the cache of [Element]s imported by [LibraryImportElement]s.