Analyzer: Fix a few dozen comment references

srawlins · Commit Queue · commit 02440ed34a79 · 2025-01-06T12:52:21.000-08:00
Change-Id: I4a028f156aeaf8db532423c627aa9644f77b518c Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/402900 Commit-Queue: Samuel Rawlins <srawlins@google.com> Reviewed-by: Konstantin Shcheglov <scheglov@google.com>
diff --git a/pkg/analyzer/lib/dart/element/element2.dart b/pkg/analyzer/lib/dart/element/element2.dart
@@ -1424,7 +1424,7 @@ abstract class JoinPatternVariableFragment implements PatternVariableFragment {
   @override
   JoinPatternVariableElement2 get element;
 
-  /// Whether the [variables] are consistent.
+  /// Whether the [variables2] are consistent.
   ///
   /// The variables are consistent if they are present in all branches, and have
   /// the same type and finality.
@@ -1796,7 +1796,7 @@ abstract class LocalFunctionElement
   LocalFunctionFragment get firstFragment;
 }
 
-/// The portion of a [LocalFunctionElement2] contributed by a single
+/// The portion of a [LocalFunctionElement] contributed by a single
 /// declaration.
 ///
 /// Clients may not extend, implement or mix-in this class.
diff --git a/pkg/analyzer/lib/src/dart/analysis/session_helper.dart b/pkg/analyzer/lib/src/dart/analysis/session_helper.dart
@@ -84,7 +84,7 @@ class AnalysisSessionHelper {
     return null;
   }
 
-  /// Return the resolved unit that declares the given [element].
+  /// Return the resolved unit that declares the given [element2].
   Future<ResolvedUnitResult?> getResolvedUnitByElement(
       Element2 element2) async {
     var element = element2.asElement;
diff --git a/pkg/analyzer/lib/src/dart/constant/evaluation.dart b/pkg/analyzer/lib/src/dart/constant/evaluation.dart
@@ -1351,9 +1351,9 @@ class ConstantVisitor extends UnifyingAstVisitor<Constant> {
   /// Builds a list constant by adding the evaluated entries of [elements] to
   /// the given [list].
   ///
-  /// The [typeSystem], [listType], and [elementType] are used to create a valid
-  /// constant. We return an [InvalidConstant] if the evaluation of any of the
-  /// elements failed.
+  /// The [typeSystem] and [listType] are used to create a valid constant. We
+  /// return an [InvalidConstant] if the evaluation of any of the elements
+  /// failed.
   Constant _buildListConstant(
     List<DartObjectImpl> list,
     List<CollectionElement> elements,
diff --git a/pkg/analyzer/lib/src/dart/resolver/extension_member_resolver.dart b/pkg/analyzer/lib/src/dart/resolver/extension_member_resolver.dart
@@ -81,10 +81,10 @@ class ExtensionMemberResolver {
   /// that defines the member with the given [name].
   ///
   /// If no applicable extensions are found, returns
-  /// [ExtensionResolutionResult.none].
+  /// [ExtensionResolutionError.none].
   ///
   /// If the match is ambiguous, reports an error on the [nameEntity], and
-  /// returns [ExtensionResolutionResult.ambiguous].
+  /// returns [ExtensionResolutionError.ambiguous].
   ExtensionResolutionResult findExtension(
       DartType type, SyntacticEntity nameEntity, Name name) {
     var extensions = _resolver.libraryFragment.accessibleExtensions
diff --git a/pkg/analyzer/lib/src/generated/error_detection_helpers.dart b/pkg/analyzer/lib/src/generated/error_detection_helpers.dart
@@ -2,6 +2,9 @@
 // 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 'package:analyzer/src/error/best_practices_verifier.dart';
+library;
+
 import 'package:_fe_analyzer_shared/src/flow_analysis/flow_analysis.dart';
 import 'package:_fe_analyzer_shared/src/types/shared_type.dart';
 import 'package:analyzer/dart/ast/ast.dart';
@@ -55,9 +58,6 @@ mixin ErrorDetectionHelpers {
   /// Verify that the given [argument] can be assigned to its corresponding
   /// parameter.
   ///
-  /// This method corresponds to
-  /// [BestPracticesVerifier.checkForArgumentTypeNotAssignableForArgument].
-  ///
   /// See [CompileTimeErrorCode.ARGUMENT_TYPE_NOT_ASSIGNABLE].
   void checkForArgumentTypeNotAssignableForArgument(Expression argument,
       {bool promoteParameterToNullable = false,
@@ -291,9 +291,9 @@ mixin ErrorDetectionHelpers {
   }
 
   /// Computes the appropriate set of context messages to report along with an
-  /// error that may have occurred because [expression] was not type promoted.
+  /// error that may have occurred because an expression was not type promoted.
   ///
-  /// If [expression] is `null`, it means the expression that was not type
+  /// If the expression is `null`, it means the expression that was not type
   /// promoted was an implicit `this`.
   ///
   /// [errorEntity] is the entity whose location will be associated with the
diff --git a/pkg/analyzer/lib/src/generated/error_verifier.dart b/pkg/analyzer/lib/src/generated/error_verifier.dart
@@ -2668,7 +2668,7 @@ class ErrorVerifier extends RecursiveAstVisitor<void>
   /// Verify all conflicts between type variable and enclosing extension.
   ///
   /// See [CompileTimeErrorCode.CONFLICTING_TYPE_VARIABLE_AND_EXTENSION], and
-  /// [CompileTimeErrorCode.CONFLICTING_TYPE_VARIABLE_AND_EXTENSION_MEMBER].
+  /// [CompileTimeErrorCode.CONFLICTING_TYPE_VARIABLE_AND_MEMBER_EXTENSION].
   void _checkForConflictingExtensionTypeVariableErrorCodes() {
     for (TypeParameterElement typeParameter
         in _enclosingExtension!.typeParameters) {
@@ -3346,7 +3346,8 @@ class ErrorVerifier extends RecursiveAstVisitor<void>
     );
   }
 
-  /// Verify that the given extends [clause] does not extend a deferred class.
+  /// Verifies that the given [superclass], found in an extends-clause, is not a
+  /// deferred class.
   ///
   /// See [CompileTimeErrorCode.EXTENDS_DEFERRED_CLASS].
   void _checkForExtendsDeferredClass(NamedType? superclass) {
@@ -3357,8 +3358,8 @@ class ErrorVerifier extends RecursiveAstVisitor<void>
         superclass, CompileTimeErrorCode.EXTENDS_DEFERRED_CLASS);
   }
 
-  /// Verify that the given extends [clause] does not extend classes such as
-  /// 'num' or 'String'.
+  /// Verifies that the given [superclass], found in an extends-clause, is not a
+  /// class such as 'num' or 'String'.
   ///
   /// See [CompileTimeErrorCode.EXTENDS_DISALLOWED_CLASS].
   bool _checkForExtendsDisallowedClass(NamedType? superclass) {
@@ -3373,8 +3374,6 @@ class ErrorVerifier extends RecursiveAstVisitor<void>
   /// classes that are deferred.
   ///
   /// See [_checkForExtendsDeferredClass],
-  /// [_checkForExtendsDeferredClassInTypeAlias],
-  /// [_checkForImplementsDeferredClass],
   /// [_checkForAllMixinErrorCodes],
   /// [CompileTimeErrorCode.EXTENDS_DEFERRED_CLASS],
   /// [CompileTimeErrorCode.IMPLEMENTS_DEFERRED_CLASS], and
@@ -3663,7 +3662,7 @@ class ErrorVerifier extends RecursiveAstVisitor<void>
 
   /// If there are no constructors in the given [members], verify that all
   /// final fields are initialized.  Cases in which there is at least one
-  /// constructor are handled in [_checkForAllFinalInitializedErrorCodes].
+  /// constructor are handled in [_checkForFinalNotInitialized].
   ///
   /// See [CompileTimeErrorCode.CONST_NOT_INITIALIZED], and
   /// [CompileTimeErrorCode.FINAL_NOT_INITIALIZED].
@@ -5394,7 +5393,7 @@ class ErrorVerifier extends RecursiveAstVisitor<void>
   }
 
   /// Verify that the given [element] does not reference itself directly.
-  /// If it does, report the error on the [node].
+  /// If it does, report the error on the [nameToken].
   ///
   /// See [CompileTimeErrorCode.TYPE_ALIAS_CANNOT_REFERENCE_ITSELF].
   void _checkForTypeAliasCannotReferenceItself(
diff --git a/pkg/analyzer/lib/src/generated/ffi_verifier.dart b/pkg/analyzer/lib/src/generated/ffi_verifier.dart
@@ -1184,7 +1184,7 @@ class FfiVerifier extends RecursiveAstVisitor<void> {
   }
 
   /// Validate that the [annotations] include exactly one annotation that
-  /// satisfies the [requiredTypes]. If an error is produced that cannot be
+  /// satisfies the [requiredType]. If an error is produced that cannot be
   /// associated with an annotation, associate it with the [errorNode].
   void _validateAnnotations(TypeAnnotation errorNode,
       NodeList<Annotation> annotations, _PrimitiveDartType requiredType) {
diff --git a/pkg/analyzer/lib/src/generated/resolver.dart b/pkg/analyzer/lib/src/generated/resolver.dart
@@ -4424,9 +4424,9 @@ class ResolverVisitor extends ThrowingAstVisitor<void>
     return true;
   }
 
-  /// Report [CompileTimeErrorCode.NOT_ENOUGH_POSITIONAL_ARGUMENTS] or one of
-  /// its derivatives at the specified [token], considering the name of the
-  /// [nameNode].
+  /// Reports [CompileTimeErrorCode.NOT_ENOUGH_POSITIONAL_ARGUMENTS_SINGULAR] or
+  /// [CompileTimeErrorCode.NOT_ENOUGH_POSITIONAL_ARGUMENTS_PLURAL] at the
+  /// specified [token], considering the name of the [nameNode].
   static void _reportNotEnoughPositionalArguments(
       {required Token token,
       required int requiredParameterCount,
diff --git a/pkg/analyzer/lib/src/generated/sdk.dart b/pkg/analyzer/lib/src/generated/sdk.dart
@@ -131,7 +131,7 @@ class LibraryMap {
   /// not map to a library.
   SdkLibrary? getLibrary(String uri) => _libraryMap[uri];
 
-  /// Set the library with the given 'dart:' [uri] to the given [library].
+  /// Set the library with the given 'dart:' [dartUri] to the given [library].
   void setLibrary(String dartUri, SdkLibraryImpl library) {
     _libraryMap[dartUri] = library;
   }
@@ -193,7 +193,7 @@ class SdkLibrariesReader_LibraryBuilder extends RecursiveAstVisitor<void> {
   /// the library can be used.
   static const String _PLATFORMS = "platforms";
 
-  /// The value of the [PLATFORMS] parameter used to specify that the library
+  /// The value of the [_PLATFORMS] parameter used to specify that the library
   /// can be used on the VM.
   static const String _VM_PLATFORM = "VM_PLATFORM";
 
@@ -333,7 +333,7 @@ class SdkLibraryImpl implements SdkLibrary {
   int _platforms = 0;
 
   /// Initialize a newly created library to represent the library with the given
-  /// [name].
+  /// [shortName].
   SdkLibraryImpl(this.shortName);
 
   /// Set whether the library is documented.
diff --git a/pkg/analyzer/lib/src/generated/source.dart b/pkg/analyzer/lib/src/generated/source.dart
@@ -122,8 +122,8 @@ abstract class SourceFactory {
   ///         there is no such SDK
   DartSdk? get dartSdk;
 
-  /// A table mapping package names to paths of directories containing
-  /// the package (or [null] if there is no registered package URI resolver).
+  /// A table mapping package names to paths of directories containing the
+  /// package (or `null` if there is no registered package URI resolver).
   Map<String, List<Folder>>? get packageMap;
 
   /// Return a source object representing the given absolute URI, or `null` if
diff --git a/pkg/analyzer/lib/src/lint/linter.dart b/pkg/analyzer/lib/src/lint/linter.dart
@@ -235,9 +235,10 @@ abstract class LintRule {
 
   set reporter(ErrorReporter value) => _reporter = value;
 
-  /// Return a visitor to be passed to pubspecs to perform lint
+  /// Returns a visitor to be passed to pubspecs to perform lint
   /// analysis.
-  /// Lint errors are reported via this [Linter]'s error [reporter].
+  ///
+  /// Lint errors are reported via this [LintRule]'s error [reporter].
   PubspecVisitor? getPubspecVisitor() => null;
 
   /// Registers node processors in the given [registry].
diff --git a/pkg/analyzer/lib/src/lint/pub.dart b/pkg/analyzer/lib/src/lint/pub.dart
@@ -199,7 +199,7 @@ abstract class PSGitRepo {
   ///   foo:
   ///     git:       https://github.com/example/example
   /// ```
-  /// Then [token] and [url.key] will be the same object.
+  /// Then [token] and `url.key` will be the same object.
   PSEntry? get url;
 }
 
diff --git a/pkg/analyzer/lib/src/manifest/manifest_validator.dart b/pkg/analyzer/lib/src/manifest/manifest_validator.dart
@@ -401,7 +401,7 @@ class ManifestValidator {
   /// [source].
   ManifestValidator(this.source);
 
-  /// Validate the [contents] of the Android Manifest file.
+  /// Validate the [content] of the Android Manifest file.
   List<AnalysisError> validate(String content, bool checkManifest) {
     // TODO(srawlins): Simplify [checkManifest] notion. Why call the method if
     //  the caller always knows whether it should just return empty?
diff --git a/pkg/analyzer/lib/src/summary/format.dart b/pkg/analyzer/lib/src/summary/format.dart
@@ -99,12 +99,12 @@ class AnalysisDriverExceptionContextBuilder extends Object
         _path = path,
         _stackTrace = stackTrace;
 
-  /// Flush [informative] data recursively.
+  /// Flush informative data recursively.
   void flushInformative() {
     _files?.forEach((b) => b.flushInformative());
   }
 
-  /// Accumulate non-[informative] data into [signature].
+  /// Accumulate non-informative data into [signatureSink].
   void collectApiSignature(api_sig.ApiSignature signatureSink) {
     signatureSink.addString(this._path ?? '');
     signatureSink.addString(this._exception ?? '');
@@ -281,10 +281,10 @@ class AnalysisDriverExceptionFileBuilder extends Object
       : _content = content,
         _path = path;
 
-  /// Flush [informative] data recursively.
+  /// Flush informative data recursively.
   void flushInformative() {}
 
-  /// Accumulate non-[informative] data into [signature].
+  /// Accumulate non-informative data into [signatureSink].
   void collectApiSignature(api_sig.ApiSignature signatureSink) {
     signatureSink.addString(this._path ?? '');
     signatureSink.addString(this._content ?? '');
@@ -400,13 +400,13 @@ class AnalysisDriverResolvedUnitBuilder extends Object
       : _errors = errors,
         _index = index;
 
-  /// Flush [informative] data recursively.
+  /// Flush informative data recursively.
   void flushInformative() {
     _errors?.forEach((b) => b.flushInformative());
     _index?.flushInformative();
   }
 
-  /// Accumulate non-[informative] data into [signature].
+  /// Accumulate non-informative data into [signatureSink].
   void collectApiSignature(api_sig.ApiSignature signatureSink) {
     var errors = this._errors;
     if (errors == null) {
@@ -526,7 +526,7 @@ class AnalysisDriverSubtypeBuilder extends Object
   List<int> get members => _members ??= <int>[];
 
   /// The names of defined instance members.
-  /// They are indexes into [AnalysisDriverUnitError.strings] list.
+  /// They are indexes into [AnalysisDriverUnitIndex.strings] list.
   /// The list is sorted in ascending order.
   set members(List<int> value) {
     assert(value.every((e) => e >= 0));
@@ -537,7 +537,7 @@ class AnalysisDriverSubtypeBuilder extends Object
   int get name => _name ??= 0;
 
   /// The name of the class.
-  /// It is an index into [AnalysisDriverUnitError.strings] list.
+  /// It is an index into [AnalysisDriverUnitIndex.strings] list.
   set name(int value) {
     assert(value >= 0);
     this._name = value;
@@ -547,10 +547,10 @@ class AnalysisDriverSubtypeBuilder extends Object
       : _members = members,
         _name = name;
 
-  /// Flush [informative] data recursively.
+  /// Flush informative data recursively.
   void flushInformative() {}
 
-  /// Accumulate non-[informative] data into [signature].
+  /// Accumulate non-informative data into [signatureSink].
   void collectApiSignature(api_sig.ApiSignature signatureSink) {
     signatureSink.addInt(this._name ?? 0);
     var members = this._members;
@@ -711,12 +711,12 @@ class AnalysisDriverUnitErrorBuilder extends Object
         _offset = offset,
         _uniqueName = uniqueName;
 
-  /// Flush [informative] data recursively.
+  /// Flush informative data recursively.
   void flushInformative() {
     _contextMessages?.forEach((b) => b.flushInformative());
   }
 
-  /// Accumulate non-[informative] data into [signature].
+  /// Accumulate non-informative data into [signatureSink].
   void collectApiSignature(api_sig.ApiSignature signatureSink) {
     signatureSink.addInt(this._offset ?? 0);
     signatureSink.addInt(this._length ?? 0);
@@ -1172,12 +1172,12 @@ class AnalysisDriverUnitIndexBuilder extends Object
         _usedNameOffsets = usedNameOffsets,
         _usedNames = usedNames;
 
-  /// Flush [informative] data recursively.
+  /// Flush informative data recursively.
   void flushInformative() {
     _subtypes?.forEach((b) => b.flushInformative());
   }
 
-  /// Accumulate non-[informative] data into [signature].
+  /// Accumulate non-informative data into [signatureSink].
   void collectApiSignature(api_sig.ApiSignature signatureSink) {
     var strings = this._strings;
     if (strings == null) {
@@ -1868,12 +1868,12 @@ class CiderUnitErrorsBuilder extends Object
   CiderUnitErrorsBuilder({List<AnalysisDriverUnitErrorBuilder>? errors})
       : _errors = errors;
 
-  /// Flush [informative] data recursively.
+  /// Flush informative data recursively.
   void flushInformative() {
     _errors?.forEach((b) => b.flushInformative());
   }
 
-  /// Accumulate non-[informative] data into [signature].
+  /// Accumulate non-informative data into [signatureSink].
   void collectApiSignature(api_sig.ApiSignature signatureSink) {
     var errors = this._errors;
     if (errors == null) {
@@ -2021,10 +2021,10 @@ class DiagnosticMessageBuilder extends Object
         _offset = offset,
         _url = url;
 
-  /// Flush [informative] data recursively.
+  /// Flush informative data recursively.
   void flushInformative() {}
 
-  /// Accumulate non-[informative] data into [signature].
+  /// Accumulate non-informative data into [signatureSink].
   void collectApiSignature(api_sig.ApiSignature signatureSink) {
     signatureSink.addString(this._filePath ?? '');
     signatureSink.addInt(this._length ?? 0);
diff --git a/pkg/analyzer/lib/src/summary/format.fbs b/pkg/analyzer/lib/src/summary/format.fbs
@@ -73,7 +73,7 @@ enum IndexRelationKind : byte {
   IS_WRITTEN_BY
 }
 
-/// When we need to reference a synthetic element in [PackageIndex] we use a
+/// When we need to reference a synthetic element in PackageIndex we use a
 /// value of this enum to specify which kind of the synthetic element we
 /// actually reference.
 enum IndexSyntheticElementKind : byte {
@@ -147,12 +147,12 @@ table AnalysisDriverResolvedUnit {
 /// Information about a subtype of one or more classes.
 table AnalysisDriverSubtype {
   /// The names of defined instance members.
-  /// They are indexes into [AnalysisDriverUnitError.strings] list.
+  /// They are indexes into [AnalysisDriverUnitIndex.strings] list.
   /// The list is sorted in ascending order.
   members:[uint] (id: 1);
 
   /// The name of the class.
-  /// It is an index into [AnalysisDriverUnitError.strings] list.
+  /// It is an index into [AnalysisDriverUnitIndex.strings] list.
   name:uint (id: 0);
 }
 
diff --git a/pkg/analyzer/lib/src/summary/idl.dart b/pkg/analyzer/lib/src/summary/idl.dart
diff --git a/pkg/analyzer/lib/src/summary2/binary_format_doc.dart b/pkg/analyzer/lib/src/summary2/binary_format_doc.dart
diff --git a/pkg/analyzer/lib/src/summary2/macro_application.dart b/pkg/analyzer/lib/src/summary2/macro_application.dart
diff --git a/pkg/analyzer/lib/src/summary2/reference_resolver.dart b/pkg/analyzer/lib/src/summary2/reference_resolver.dart
diff --git a/pkg/analyzer/tool/summary/generate.dart b/pkg/analyzer/tool/summary/generate.dart

Original file line number	Diff line number	Diff line change
`@@ -84,7 +84,7 @@ class AnalysisSessionHelper {`
`84`	`84`	`return null;`
`85`	`85`	`}`
`86`	`86`
`87`		`- /// Return the resolved unit that declares the given [element].`
	`87`	`+ /// Return the resolved unit that declares the given [element2].`
`88`	`88`	`Future<ResolvedUnitResult?> getResolvedUnitByElement(`
`89`	`89`	`Element2 element2) async {`
`90`	`90`	`var element = element2.asElement;`
Original file line number	Diff line number	Diff line change
`@@ -1184,7 +1184,7 @@ class FfiVerifier extends RecursiveAstVisitor<void> {`
`1184`	`1184`	`}`
`1185`	`1185`
`1186`	`1186`	`/// Validate that the [annotations] include exactly one annotation that`
`1187`		`- /// satisfies the [requiredTypes]. If an error is produced that cannot be`
	`1187`	`+ /// satisfies the [requiredType]. If an error is produced that cannot be`
`1188`	`1188`	`/// associated with an annotation, associate it with the [errorNode].`
`1189`	`1189`	`void _validateAnnotations(TypeAnnotation errorNode,`
`1190`	`1190`	`NodeList<Annotation> annotations, _PrimitiveDartType requiredType) {`