[analyzer] Enable the comment_references lint.

Fixes trivial typos and adds `@docImport` declarations so that no
dangling comment references remain in the `analyzer` package, and
enables the `comment_references` lint so that dangling comment
references won't be added in the future.

Change-Id: I6a6a696466de07d6a07fe9f0afe875019bc44c71
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/450743
Reviewed-by: Konstantin Shcheglov <[email protected]>
Commit-Queue: Konstantin Shcheglov <[email protected]>
Auto-Submit: Paul Berry <[email protected]>

Author: stereotype441

pkg/analyzer/analysis_options.yaml

@@ -54,6 +54,7 @@ linter:
     - avoid_dynamic_calls
     - avoid_redundant_argument_values
     - avoid_unused_constructor_parameters
+    - comment_references
     - discarded_futures
     - flutter_style_todos
     - no_literal_bool_comparisons

pkg/analyzer/lib/dart/analysis/results.dart

@@ -66,7 +66,7 @@ abstract class ElementDeclarationResult {
   /// The [Fragment] that this object describes.
   Fragment get fragment;
 
-  /// The node that declares the [element]. Depending on whether it is returned
+  /// The node that declares the [Element]. Depending on whether it is returned
   /// from [ResolvedLibraryResult] or [ParsedLibraryResult] it might be resolved
   /// or just parsed.
   AstNode get node;

pkg/analyzer/lib/src/dart/analysis/results.dart

@@ -44,7 +44,7 @@ abstract class AnalysisResultImpl implements AnalysisResult {
   AnalysisResultImpl({required this.session});
 }
 
-/// A visitor which locates the [AstNode] which declares [element].
+/// A visitor which locates the [AstNode] which declares an [Element].
 class DeclarationByElementLocator extends UnifyingAstVisitor<void> {
   // TODO(srawlins): This visitor could be further optimized by special casing each static
   // type of [element]. For example, for library-level elements (classes etc),

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

@@ -3386,7 +3386,7 @@ class FormalParameterFragmentImpl extends VariableFragmentImpl
   }) : assert(nameOffset == null || nameOffset >= 0),
        assert(name == null || name.isNotEmpty);
 
-  /// Creates a synthetic parameter with [name2], [type] and [parameterKind].
+  /// Creates a synthetic parameter with [name2] and [parameterKind].
   factory FormalParameterFragmentImpl.synthetic(
     String? name2,
     ParameterKind parameterKind,
@@ -3600,8 +3600,7 @@ abstract class FragmentImpl with _FragmentImplMixin implements Fragment {
   /// The length of the element's code, or `null` if the element is synthetic.
   int? _codeLength;
 
-  /// Initialize a newly created element to have the given [name] at the given
-  /// [_nameOffset].
+  /// Initialize a newly created fragment at the given [firstTokenOffset].
   FragmentImpl({this.firstTokenOffset});
 
   /// The length of the element's code, or `null` if the element is synthetic.
@@ -5989,7 +5988,7 @@ class LibraryElementImpl extends ElementImpl
   );
 
   /// Initialize a newly created library element in the given [context] to have
-  /// the given [name] and [offset].
+  /// the given [name] and [nameOffset].
   LibraryElementImpl(
     this._context,
     this._session,

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

@@ -756,7 +756,7 @@ class TypeSystemImpl implements TypeSystem {
     );
   }
 
-  /// Given uninstantiated [typeFormals], instantiate them to their bounds.
+  /// Given uninstantiated [typeParameters], instantiate them to their bounds.
   /// See the issue for the algorithm description.
   ///
   /// https://github.com/dart-lang/sdk/issues/27526#issuecomment-260021397

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

@@ -76,8 +76,8 @@ ConstructorElement? _getActualConstructorElement(
   return constructor;
 }
 
-/// Returns the [LibraryImportElement] that is referenced by [prefixNode] with a
-/// [PrefixElement], maybe `null`.
+/// Returns the [MockLibraryImportElement] that is referenced by [prefixNode]
+/// with a [PrefixElement], maybe `null`.
 MockLibraryImportElement? _getImportElementInfo2(SimpleIdentifier prefixNode) {
   // prepare environment
   var parent = prefixNode.parent;
@@ -114,8 +114,8 @@ MockLibraryImportElement? _getImportElementInfo2(SimpleIdentifier prefixNode) {
   );
 }
 
-/// Returns the [LibraryImportElement] that is referenced by [prefixNode] with a
-/// [PrefixElement], maybe `null`.
+/// Returns the [MockLibraryImportElement] that is referenced by [prefixNode]
+/// with a [PrefixElement], maybe `null`.
 MockLibraryImportElement? _getImportElementInfoFromReference(
   ImportPrefixReference prefixNode,
 ) {
@@ -149,12 +149,13 @@ MockLibraryImportElement? _getImportElementInfoFromReference(
   );
 }
 
-/// Returns the [LibraryImportElement] that declared [prefix] and imports [element].
+/// Returns the [MockLibraryImportElement] that declared [prefix] and imports
+/// [element].
 ///
 /// [libraryFragment] - the [LibraryFragmentImpl] where reference is.
 /// [prefix] - the import prefix, maybe `null`.
 /// [element] - the referenced element.
-/// [importElementsMap] - the cache of [Element]s imported by [LibraryImportElement]s.
+/// [importElementsMap] - the cache of [Element]s imported by [LibraryImport]s.
 MockLibraryImportElement? _getMockImportElement(
   LibraryFragmentImpl libraryFragment,
   String prefix,

pkg/analyzer/lib/src/error/codes.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 'package:analyzer/src/dart/error/syntactic_errors.dart';
+/// @docImport 'package:analyzer/src/error/inference_error.dart';
+library;
+
 import 'package:_fe_analyzer_shared/src/base/errors.dart';
 import 'package:analyzer/dart/element/element.dart';
 import 'package:analyzer/dart/element/type.dart';

pkg/analyzer/lib/src/error/ignore_validator.dart

@@ -50,7 +50,7 @@ class IgnoreValidator {
 
   /// Initialize a newly created validator to report any issues with ignore
   /// comments in the file being analyzed. The diagnostics will be reported to
-  /// the [_errorReporter].
+  /// the [_diagnosticReporter].
   IgnoreValidator(
     this._diagnosticReporter,
     this._reportedDiagnostics,

pkg/analyzer/lib/src/error/listener.dart

@@ -405,8 +405,8 @@ class DiagnosticReporter {
   }
 }
 
-/// Used by [DiagnosticReporter._convertTypeNames] to keep track of an error
-/// argument that is an [Element], that is being converted to a display string.
+/// Used by [convertTypeNames] to keep track of an error argument that is an
+/// [Element], that is being converted to a display string.
 class _ElementToConvert implements _ToConvert {
   @override
   final int index;
@@ -421,8 +421,8 @@ class _ElementToConvert implements _ToConvert {
     : allElements = [element];
 }
 
-/// Used by [DiagnosticReporter._convertTypeNames] to keep track of an argument
-/// that is being converted to a display string.
+/// Used by [convertTypeNames] to keep track of an argument that is being
+/// converted to a display string.
 abstract class _ToConvert {
   /// A list of all elements involved in the [DartType] or [Element]'s display
   /// string.
@@ -436,8 +436,8 @@ abstract class _ToConvert {
   int get index;
 }
 
-/// Used by [DiagnosticReporter._convertTypeNames] to keep track of an error
-/// argument that is a [DartType], that is being converted to a display string.
+/// Used by [convertTypeNames] to keep track of an error argument that is a
+/// [DartType], that is being converted to a display string.
 class _TypeToConvert implements _ToConvert {
   @override
   final int index;

pkg/analyzer/lib/src/generated/exhaustiveness.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/codes.dart';
+library;
+
 import 'package:_fe_analyzer_shared/src/exhaustiveness/dart_template_buffer.dart';
 import 'package:_fe_analyzer_shared/src/exhaustiveness/exhaustive.dart';
 import 'package:_fe_analyzer_shared/src/exhaustiveness/key.dart';
@@ -477,8 +480,8 @@ class MissingPatternEnumValuePart extends MissingPatternPart {
 
 abstract class MissingPatternPart {
   /// Expando associating each
-  /// [CompileTimeErrorCode.NON_EXHAUSTIVE_SWITCH_EXPRESSION] or
-  /// [CompileTimeErrorCode.NON_EXHAUSTIVE_SWITCH_STATEMENT] diagnostic with a
+  /// [CompileTimeErrorCode.nonExhaustiveSwitchExpression] or
+  /// [CompileTimeErrorCode.nonExhaustiveSwitchStatement] diagnostic with a
   /// list of missing patterns; this data is used by the analysis server to add
   /// missing switch cases.
   static final byDiagnostic = Expando<List<List<MissingPatternPart>>>();