Fix violations of comment_references lint (#4348)

analysis_options.yaml

@@ -3,7 +3,6 @@ include: package:dart_flutter_team_lints/analysis_options.yaml
 analyzer:
   errors:
     lines_longer_than_80_chars: ignore # TODO(mosum): fix the offending lines
-    comment_references: ignore # TODO(mosum): fix the offending lines
     todo: ignore
   exclude:
    - lib/src/third_party/**

lib/src/authentication/client.dart

@@ -17,7 +17,7 @@ import 'credential.dart';
 /// This client authenticates requests by injecting `Authentication` header to
 /// requests.
 ///
-/// Requests to URLs not under [serverBaseUrl] will not be authenticated.
+/// Requests to URLs not under [_credential]'s url will not be authenticated.
 class _AuthenticatedClient extends http.BaseClient {
   /// Constructs Http client wrapper that injects `authorization` header to
   /// requests and handles authentication errors.

lib/src/command/add.dart

@@ -369,8 +369,8 @@ Specify multiple sdk packages with descriptors.''');
     r'(?::(?<descriptor>.*))?$',
   );
 
-  /// Split [arg] on ':' and interpret it with the flags in [argResult] either as
-  /// an old-style or a new-style descriptor to produce a PackageRef].
+  /// Split [arg] on ':' and interpret it with the flags in [argResults] either
+  /// as an old-style or a new-style descriptor to produce a PackageRef].
   _ParseResult _parsePackage(String arg, ArgResults argResults) {
     var isDev = argResults.flag('dev');
     var isOverride = false;
@@ -557,9 +557,9 @@ Specify multiple sdk packages with descriptors.''');
     return _PartialParseResult(ref, constraint);
   }
 
-  /// Parse [package] to return the corresponding [_ParseResult].
+  /// Parse [packageName] to return the corresponding [_ParseResult].
   ///
-  /// [package] must be written in the format
+  /// [packageName] must be written in the format
   /// `<package-name>[:descriptor>]`, where quotations should be used if
   /// necessary.
   ///
@@ -589,16 +589,16 @@ Specify multiple sdk packages with descriptors.''');
   /// non-string descriptor.
   ///
   /// If a version constraint is provided when the `--path` or any of the
-  /// `--git-<option>` options are used, a [PackageParseError] will be thrown.
+  /// `--git-<option>` options are used, a [usageException] will be thrown.
   ///
   /// Packages must either be a git, hosted, sdk, or path package. Mixing of
-  /// options is not allowed and will cause a [PackageParseError] to be thrown.
+  /// options is not allowed and will cause a [usageException] to be thrown.
   ///
   /// If any of the other git options are defined when `--git-url` is not
   /// defined, an error will be thrown.
   ///
-  /// Returns a `ref` of `null` if the descriptor did not specify a source.
-  /// Then the source will be determined by the old-style arguments.
+  /// Returns a `ref` of `null` if the descriptor did not specify a source. Then
+  /// the source will be determined by the old-style arguments.
   _PartialParseResult _parseDescriptorNewStyle(
     String packageName,
     String? descriptor,

lib/src/command/outdated.dart

@@ -408,7 +408,7 @@ Consider using the Dart 2.19 sdk to migrate to null safety.''');
     return false;
   }();
 
-  /// Retrieves the pubspec of package [name] in [version] from [source].
+  /// Retrieves the pubspec of package [id] from its [PackageId.source].
   ///
   /// Returns `null`, if given `null` as a convinience.
   Future<_VersionDetails?> _describeVersion(
@@ -462,8 +462,8 @@ Consider using the Dart 2.19 sdk to migrate to null safety.''');
   }
 }
 
-/// Try to solve [pubspec] return [PackageId]s in the resolution or `null` if no
-/// resolution was found.
+/// Try to resolve the pubspec of [package] return [PackageId]s in the
+/// resolution or `null` if no resolution was found.
 Future<List<PackageId>?> _tryResolve(
   Package package,
   SystemCache cache, {

lib/src/dart.dart

@@ -38,9 +38,8 @@ class AnalysisContextManager {
 
   /// Parse the file with the given [path] into AST.
   ///
-  /// One of the containing directories must be used to create analysis
-  /// contexts using [createContextsForDirectory]. Throws [StateError] if
-  /// this has not been done.
+  /// One of the containing directories must have been used to create `this`.
+  /// Throws [StateError] otherwise.
   ///
   /// Throws [AnalyzerErrorGroup] is the file has parsing errors.
   CompilationUnit parse(String path) {

lib/src/entrypoint.dart

@@ -324,7 +324,7 @@ See $workspacesDocUrl for more information.''',
   /// An entrypoint for the workspace containing [workingDir]/
   ///
   /// If [checkInCache] is `true` (the default) an error will be thrown if
-  /// [rootDir] is located inside [cache.rootDir].
+  /// [workingDir] is located inside [cache]`.rootDir`.
 
   Entrypoint(
     this.workingDir,
@@ -504,7 +504,7 @@ See $workspacesDocUrl for more information.''',
   /// if [summaryOnly] is `true` only success or failure will be
   /// shown --- in case of failure, a reproduction command is shown.
   ///
-  /// Updates [lockFile] and [packageRoot] accordingly.
+  /// Updates [lockFile] and [packageGraph] accordingly.
   ///
   /// If [enforceLockfile] is true no changes to the current lockfile are
   /// allowed. Instead the existing lockfile is loaded, verified against
@@ -659,7 +659,7 @@ To update `$lockFilePath` run `$topLevelProgram pub get`$suffix without
     });
   }
 
-  /// Precompiles executable .dart file at [path] to a snapshot.
+  /// Precompiles [executable] to a snapshot.
   ///
   /// The [additionalSources], if provided, instruct the compiler to include
   /// additional source files into compilation even if they are not referenced
@@ -702,13 +702,11 @@ To update `$lockFilePath` run `$topLevelProgram pub get`$suffix without
     cache.maintainCache();
   }
 
-  /// The location of the snapshot of the dart program at [path] in [package]
+  /// The location of the snapshot of the dart program at [executable]
   /// will be stored here.
   ///
   /// We use the sdk version to make sure we don't run snapshots from a
   /// different sdk.
-  ///
-  /// [path] must be relative.
   String pathOfSnapshot(Executable executable) {
     return isCachedGlobal
         ? executable.pathOfGlobalSnapshot(workspaceRoot.dir)
@@ -732,8 +730,8 @@ To update `$lockFilePath` run `$topLevelProgram pub get`$suffix without
     }
   }
 
-  /// Does a fast-pass check to see if the resolution is up-to-date
-  /// ([_isUpToDate]). If not, run a resolution with `pub get` semantics.
+  /// Does a fast-pass check to see if the resolution is up-to-date. If not, run
+  /// a resolution with `pub get` semantics.
   ///
   /// If [summaryOnly] is `true` (the default) only a short summary is shown of
   /// the solve.
@@ -1432,8 +1430,9 @@ See https://dart.dev/go/sdk-constraint
     return result;
   }
 
-  /// Unless [dryRun], loads `pubspec.yaml` of each [package] in [changeSet] and applies the
-  /// changes to its (dev)-dependencies using yaml_edit to preserve textual structure.
+  /// Unless [dryRun], loads `pubspec.yaml` of each [Package] in [changeSet] and
+  /// applies the changes to its (dev)-dependencies using yaml_edit to preserve
+  /// textual structure.
   ///
   /// Outputs a summary of changes done or would have been done if not [dryRun].
   void applyChanges(ChangeSet changeSet, bool dryRun) {

lib/src/executable.dart

@@ -30,17 +30,17 @@ List<String> vmArgsFromArgResults(ArgResults argResults) {
   ];
 }
 
-/// Runs [executable] from [package] reachable from [entrypoint].
+/// Runs [executable] reachable from [entrypoint].
 ///
-/// The [executable] is a relative path to a Dart file within [package], which
-/// should either be the entrypoint package or an immediate dependency of it.
+/// The [executable] references Dart file, which should either be the entrypoint
+/// package or an immediate dependency of it.
 ///
 /// Arguments from [args] will be passed to the spawned Dart application.
 ///
 /// If [enableAsserts] is true, the program is run with assertions enabled.
 ///
 /// If the executable is in an immutable package and we pass no [vmArgs], it
-/// run from snapshot (and built if the snapshot doesn't already exist).
+/// runs from snapshot (and built if the snapshot doesn't already exist).
 ///
 /// Returns the exit code of the spawned app.
 Future<int> runExecutable(
@@ -253,7 +253,7 @@ final class DartExecutableWithPackageConfig {
 /// * Otherwise let `<current>` be the name of the innermost package containing
 ///   [root], and interpret [descriptor] as `[<package>][:<command>]`.
 ///
-///   * If `<package>` is empty: default to the package at [current].
+///   * If `<package>` is empty: default to the current package.
 ///   * If `<command>` is empty, resolve it as `bin/<package>.dart` or
 ///     `bin/main.dart` to the first that exists.
 ///
@@ -531,13 +531,11 @@ class Executable {
     );
   }
 
-  /// The location of the snapshot of the dart program at [path] in [package]
-  /// will be stored here.
+  /// The location of the snapshot of the dart program at [relativePath] in
+  /// [package] will be stored here.
   ///
   /// We use the sdk version to make sure we don't run snapshots from a
   /// different sdk.
-  ///
-  /// [path] must be relative.
   String pathOfSnapshot(String rootDir) {
     assert(p.isRelative(relativePath));
     final versionSuffix = sdk.version;

lib/src/global_packages.dart

@@ -81,8 +81,6 @@ class GlobalPackages {
   /// If `null`, all executables in the package will get binstubs. If empty, no
   /// binstubs will be created.
   ///
-  /// The [features] map controls which features of the package to activate.
-  ///
   /// If [overwriteBinStubs] is `true`, any binstubs that collide with
   /// existing binstubs in other packages will be overwritten by this one's.
   /// Otherwise, the previous ones will be preserved.
@@ -138,16 +136,16 @@ class GlobalPackages {
     );
   }
 
-  /// Finds the latest version of the hosted package with [name] that matches
-  /// [constraint] and makes it the active global version.
+  /// Finds the latest version of the hosted package that matches [range] and
+  /// makes it the active global version.
   ///
   /// [executables] is the names of the executables that should have binstubs.
   /// If `null`, all executables in the package will get binstubs. If empty, no
   /// binstubs will be created.
   ///
-  /// if [overwriteBinStubs] is `true`, any binstubs that collide with
-  /// existing binstubs in other packages will be overwritten by this one's.
-  /// Otherwise, the previous ones will be preserved.
+  /// if [overwriteBinStubs] is `true`, any binstubs that collide with existing
+  /// binstubs in other packages will be overwritten by this one's. Otherwise,
+  /// the previous ones will be preserved.
   ///
   /// [url] is an optional custom pub server URL. If not null, the package to be
   /// activated will be fetched from this URL instead of the default pub URL.
@@ -425,7 +423,7 @@ try:
     return entrypoint;
   }
 
-  /// Runs [package]'s [executable] with [args].
+  /// Runs [executable] with [args].
   ///
   /// If [executable] is available in its built form, that will be
   /// recompiled if the SDK has been upgraded since it was first compiled and

lib/src/http.dart

@@ -425,7 +425,7 @@ extension RequestSending on http.Client {
   /// when you need to send a request object but want a regular response object.
   ///
   /// If false is passed for [throwIfNotOk], the response will not be validated.
-  /// See [http.BaseResponse.throwIfNotOk] extension for validation details.
+  /// See [http.BaseResponse] extension for validation details.
   Future<http.Response> fetch(
     http.BaseRequest request, {
     bool throwIfNotOk = true,
@@ -442,7 +442,7 @@ extension RequestSending on http.Client {
   /// is successful, returns a [http.StreamedResponse].
   ///
   /// If false is passed for [throwIfNotOk], the response will not be validated.
-  /// See [http.BaseResponse.throwIfNotOk] extension for validation details.
+  /// See [Throwing.throwIfNotOk] extension for validation details.
   Future<http.StreamedResponse> fetchAsStream(
     http.BaseRequest request, {
     bool throwIfNotOk = true,

lib/src/ignore.dart

@@ -52,21 +52,21 @@ final class Ignore {
   /// Create an [Ignore] instance with a set of [`.gitignore` compatible][1]
   /// patterns.
   ///
-  /// Each value in [patterns] will be interpreted as one or more lines from
-  /// a `.gitignore` file, in compliance with the [`.gitignore` manual page][1].
+  /// Each value in [patterns] will be interpreted as one or more lines from a
+  /// `.gitignore` file, in compliance with the [`.gitignore` manual page][1].
   ///
   /// The keys of 'pattern' are the directories to interpret the rules relative
   /// to. The root should be the empty string, and sub-directories are separated
   /// by '/' (but no final '/').
   ///
   /// If [ignoreCase] is `true`, patterns will be case-insensitive. By default
   /// `git` is case-sensitive. But case insensitivity can be enabled when a
-  /// repository is created, or by configuration option, see
-  /// [`core.ignoreCase` documentation][2] for details.
+  /// repository is created, or by configuration option, see [`core.ignoreCase`
+  /// documentation][2] for details.
   ///
   /// If [onInvalidPattern] is passed, it will be called with a
-  /// [FormatException] describing the problem. The exception will have [source]
-  /// as source.
+  /// [FormatException] describing the problem. The exception will have the
+  /// pattern as source.
   ///
   /// **Example**:
   /// ```dart
@@ -89,8 +89,8 @@ final class Ignore {
   /// }
   /// ```
   ///
-  /// [1]: https://git-scm.com/docs/gitignore
-  /// [2]: https://git-scm.com/docs/git-config#Documentation/git-config.txt-coreignoreCase
+  /// [1]: https://git-scm.com/docs/gitignore [2]:
+  /// https://git-scm.com/docs/git-config#Documentation/git-config.txt-coreignoreCase
   Ignore(
     List<String> patterns, {
     bool ignoreCase = false,
@@ -164,29 +164,30 @@ final class Ignore {
   }
 
   /// Returns all the files in the tree under (and including) [beneath] not
-  /// ignored by ignore-files from [root] and down.
+  /// ignored by ignore-files from the "root" path '.' and down.
   ///
   /// Represents paths normalized  using '/' as directory separator. The empty
   /// relative path is '.', no '..' are allowed.
   ///
-  /// [beneath] must start with [root] and even if it is a directory it should not
-  /// end with '/', if [beneath] is not provided, everything under root is
-  /// included.
+  /// [beneath] must be relative to the root and even if it is a directory it
+  /// should not end with '/', if [beneath] is not provided, everything under
+  /// the root '.' is included.
   ///
   /// [listDir] should enumerate the immediate contents of a given directory,
-  /// returning paths including [root].
+  /// returning paths including the root '.'. This function can be used to list
+  /// directories relative to any root.
   ///
   /// [isDir] should return true if the argument is a directory. It will only be
   /// queried with file-names under (and including) [beneath]
   ///
-  /// [ignoreForDir] should retrieve the ignore rules for a single directory
-  /// or return `null` if there is no ignore rules.
+  /// [ignoreForDir] should retrieve the ignore rules for a single directory or
+  /// return `null` if there is no ignore rules.
   ///
   /// If [includeDirs] is true non-ignored directories will be included in the
   /// result (including beneath).
   ///
-  /// This example program lists all files under second argument that are
-  /// not ignored by .gitignore files from first argument and below:
+  /// This example program lists all files under second argument that are not
+  /// ignored by .gitignore files from first argument and below:
   ///
   /// ```dart
   /// import 'dart:io';

lib/src/io.dart

@@ -105,8 +105,8 @@ FileStat statPath(String path) {
 
 /// Returns the canonical path for [pathString].
 ///
-/// This is the normalized, absolute path, with symlinks resolved. As in
-/// [transitiveTarget], broken or recursive symlinks will not be fully resolved.
+/// This is the normalized, absolute path, with symlinks resolved. Broken or
+/// recursive symlinks will not be fully resolved.
 ///
 /// This doesn't require [pathString] to point to a path that exists on the
 /// filesystem; nonexistent or unreadable path entries are treated as normal
@@ -319,7 +319,7 @@ String ensureDir(String dir) {
   return dir;
 }
 
-/// Creates a temp directory in [dir], whose name will be [prefix] with
+/// Creates a temp directory in [base], whose name will be [prefix] with
 /// characters appended to it to make a unique name.
 ///
 /// Returns the path of the created directory.

lib/src/log.dart

@@ -43,8 +43,6 @@ const _maxTranscript = 10000;
 final Transcript<_Entry> _transcript = Transcript(_maxTranscript);
 
 /// The currently-animated progress indicator, if any.
-///
-/// This will also be in [_progresses].
 Progress? _animatedProgress;
 
 final _cyan = getAnsi('\u001b[36m');

lib/src/oauth2.dart

@@ -738,7 +738,7 @@ class _Client extends http.BaseClient {
   /// Creates a new client from a pre-existing set of credentials.
   ///
   /// When authorizing a client for the first time, you should use
-  /// [_AuthorizationCodeGrant] or [_resourceOwnerPasswordGrant] instead of
+  /// [_AuthorizationCodeGrant] instead of
   /// constructing a [_Client] directly.
   ///
   /// [httpClient] is the underlying client that this forwards requests to after

lib/src/progress.dart

@@ -30,8 +30,8 @@ class Progress {
 
   /// Creates a new progress indicator.
   ///
-  /// If [fine] is passed, this will log progress messages on [log.Level.FINE]
-  /// as opposed to [log.Level.MESSAGE].
+  /// If [fine] is passed, this will log progress messages on [log.Level.fine]
+  /// as opposed to [log.Level.message].
   Progress(this._message, {bool fine = false}) {
     _stopwatch.start();