analyzer: Correct comment references in some source files

This corrects about 40 of 220 comment_references issues in the analyzer
package.

In correcting the `experimentStatusToStringList` function, I see that
it is unused.

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

Author: srawlins

pkg/analyzer/lib/dart/analysis/utilities.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/dart/analysis/session.dart';
+library;
+
 import 'package:analyzer/dart/analysis/analysis_context.dart';
 import 'package:analyzer/dart/analysis/analysis_context_collection.dart';
 import 'package:analyzer/dart/analysis/features.dart';

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

@@ -116,7 +116,7 @@ abstract class AugmentedInstanceElement {
 
   /// The fields declared in this element.
   ///
-  /// [FieldAugmentationElement]s replace corresponding elements, other
+  /// `FieldAugmentationElement`s replace corresponding elements, other
   /// [FieldElement]s are appended.
   List<FieldElement> get fields;
 
@@ -131,7 +131,7 @@ abstract class AugmentedInstanceElement {
 
   /// The methods declared in this element.
   ///
-  /// [MethodAugmentationElement]s replace corresponding elements, other
+  /// `MethodAugmentationElement`s replace corresponding elements, other
   /// [MethodElement]s are appended.
   List<MethodElement> get methods;
 
@@ -190,7 +190,7 @@ abstract class AugmentedInstanceElement {
 abstract class AugmentedInterfaceElement implements AugmentedInstanceElement {
   /// The constructors declared in this element.
   ///
-  /// [ConstructorAugmentationElement]s replace corresponding elements,
+  /// `ConstructorAugmentationElement`s replace corresponding elements,
   /// other [ConstructorElement]s are appended.
   List<ConstructorElement> get constructors;
 

pkg/analyzer/lib/dart/element/element2.dart

@@ -42,6 +42,7 @@
 /// statements declares a local variable then the local variable will be
 /// represented by an element.
 ///
+/// @docImport 'package:analyzer/dart/element/element.dart';
 /// @docImport 'package:analyzer/src/dart/element/member.dart';
 library;
 
@@ -1171,7 +1172,7 @@ abstract class InterfaceFragment implements InstanceFragment {
 ///
 /// Clients may not extend, implement or mix-in this class.
 abstract class JoinPatternVariableElement2 implements PatternVariableElement2 {
-  /// Whether the [variables] are consistent, present in all branches,
+  /// Whether the [variables2] are consistent, present in all branches,
   /// and have the same type and finality.
   bool get isConsistent;
 

pkg/analyzer/lib/dart/element/visitor2.dart

@@ -187,8 +187,8 @@ class GeneralizingElementVisitor2<R> implements ElementVisitor2<R> {
 
 /// A visitor that will recursively visit all of the element in an element
 /// model. For example, using an instance of this class to visit a
-/// [CompilationUnitElement] will also cause all of the types in the compilation
-/// unit to be visited.
+/// [LibraryFragment] will also cause all of the types in the fragment to be
+/// visited.
 ///
 /// Subclasses that override a visit method must either invoke the overridden
 /// visit method or must explicitly ask the visited element to visit its

pkg/analyzer/lib/error/listener.dart

@@ -58,9 +58,11 @@ class ErrorReporter {
   @internal
   int lockLevel = 0;
 
-  /// Initialize a newly created error reporter that will report errors to the
-  /// given [_errorListener]. Errors will be reported against the
-  /// [_defaultSource] unless another source is provided later.
+  /// Initializes a newly created error reporter that will report errors to the
+  /// given [_errorListener].
+  ///
+  /// Errors will be reported against the [_source] unless another source is
+  /// provided later.
   ErrorReporter(this._errorListener, this._source);
 
   Source get source => _source;

pkg/analyzer/lib/file_system/memory_file_system.dart

@@ -50,7 +50,8 @@ class MemoryResourceProvider implements ResourceProvider {
   @override
   pathos.Context get pathContext => _pathContext;
 
-  /// Convert the given posix [path] to conform to this provider's path context.
+  /// Converts the given posix [filePath] to conform to this provider's path
+  /// context.
   ///
   /// This is a utility method for testing; paths passed in to other methods in
   /// this class are never converted automatically.
@@ -605,7 +606,7 @@ abstract class _MemoryResource implements Resource {
   /// Watch for changes to the files inside this folder (and in any nested
   /// folders, including folders reachable via links).
   ///
-  /// If [provider.delayWatcherInitialization] is not `null`, this method will
+  /// If `provider.delayWatcherInitialization` is not `null`, this method will
   /// wait for this amount of time before it starts capturing/streaming events
   /// to simulate the delay that occurs when initializing a real file system
   /// watcher.

pkg/analyzer/lib/file_system/overlay_file_system.dart

@@ -110,7 +110,7 @@ class OverlayResourceProvider implements ResourceProvider {
   }
 
   /// Return the paths of all of the overlaid files that are children of the
-  /// given [folder], either directly or indirectly.
+  /// given [folderPath], either directly or indirectly.
   Iterable<String> _overlaysInFolder(String folderPath) => _overlays.keys
       .where((filePath) => pathContext.isWithin(folderPath, filePath));
 }

pkg/analyzer/lib/source/file_source.dart

@@ -45,9 +45,9 @@ class FileSource extends Source {
 
   /// Get and return the contents and timestamp of the underlying file.
   ///
-  /// Clients should consider using the method [AnalysisContext.getContents]
-  /// because contexts can have local overrides of the content of a source that
-  /// the source is not aware of.
+  /// Clients should consider using the method
+  /// `AnalysisSession.getFile('...').contents` because contexts can have local
+  /// overrides of the content of a source that the source is not aware of.
   ///
   /// Throws an exception if the contents of this source could not be accessed.
   /// See [contents].

pkg/analyzer/lib/source/source.dart

@@ -71,11 +71,9 @@ abstract class Source {
 
   /// Return `true` if this source exists.
   ///
-  /// Clients should consider using the method [AnalysisContext.exists] because
-  /// contexts can have local overrides of the content of a source that the
-  /// source is not aware of and a source with local content is considered to
-  /// exist even if there is no file on disk.
-  ///
-  /// @return `true` if this source exists
+  /// Clients should consider using the method `AnalysisSession.getFile` (and
+  /// checking for an invalid result) because contexts can have local overrides
+  /// of the content of a source that the source is not aware of and a source
+  /// with local content is considered to exist even if there is no file on disk.
   bool exists();
 }

pkg/analyzer/lib/src/dart/analysis/analysis_options_map.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/dart/analysis/analysis_options.dart';
+library;
+
 import 'package:analyzer/file_system/file_system.dart';
 import 'package:analyzer/src/dart/analysis/analysis_options.dart';