From 7a7cbe67512c83ec68a2a7eea3ed5e4fd584e46c Mon Sep 17 00:00:00 2001
From: Sigurd Meldgaard <sigurdm@google.com>
Date: Tue, 27 Aug 2024 11:59:11 +0200
Subject: [PATCH] Fix violations of comment_references lint (#4348)

---
 analysis_options.yaml                       |  1 -
 lib/src/authentication/client.dart          |  2 +-
 lib/src/command/add.dart                    | 16 +++++-----
 lib/src/command/outdated.dart               |  6 ++--
 lib/src/dart.dart                           |  5 ++-
 lib/src/entrypoint.dart                     | 19 ++++++-----
 lib/src/executable.dart                     | 16 +++++-----
 lib/src/global_packages.dart                | 14 ++++-----
 lib/src/http.dart                           |  4 +--
 lib/src/ignore.dart                         | 35 +++++++++++----------
 lib/src/io.dart                             |  6 ++--
 lib/src/log.dart                            |  2 --
 lib/src/oauth2.dart                         |  2 +-
 lib/src/progress.dart                       |  4 +--
 lib/src/pubspec.dart                        |  8 ++---
 lib/src/pubspec_utils.dart                  |  4 +--
 lib/src/rate_limited_scheduler.dart         |  2 +-
 lib/src/solver/package_lister.dart          |  2 +-
 lib/src/solver/partial_solution.dart        |  4 +--
 lib/src/solver/report.dart                  |  3 +-
 lib/src/solver/version_solver.dart          |  9 +++---
 lib/src/source.dart                         | 13 ++++----
 lib/src/source/cached.dart                  | 13 ++++----
 lib/src/source/git.dart                     |  6 ++--
 lib/src/source/hosted.dart                  | 13 +++-----
 lib/src/system_cache.dart                   |  5 ---
 test/descriptor.dart                        | 12 +++----
 test/descriptor/tar.dart                    |  2 +-
 test/embedding/ensure_pubspec_resolved.dart |  4 ---
 test/package_server.dart                    |  3 +-
 test/test_pub.dart                          |  4 +--
 tool/extract_all_pub_dev.dart               |  2 +-
 32 files changed, 107 insertions(+), 134 deletions(-)

diff --git a/analysis_options.yaml b/analysis_options.yaml
index c1d8ab7a9..c820ffe47 100644
--- a/analysis_options.yaml
+++ b/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/**
diff --git a/lib/src/authentication/client.dart b/lib/src/authentication/client.dart
index 412e3f436..2b4e83534 100644
--- a/lib/src/authentication/client.dart
+++ b/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.
diff --git a/lib/src/command/add.dart b/lib/src/command/add.dart
index 6199c5fd1..87ac45b6d 100644
--- a/lib/src/command/add.dart
+++ b/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,
diff --git a/lib/src/command/outdated.dart b/lib/src/command/outdated.dart
index 904a4acf5..19235b284 100644
--- a/lib/src/command/outdated.dart
+++ b/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, {
diff --git a/lib/src/dart.dart b/lib/src/dart.dart
index 1ed734fff..f36fc831b 100644
--- a/lib/src/dart.dart
+++ b/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) {
diff --git a/lib/src/entrypoint.dart b/lib/src/entrypoint.dart
index e2b2c5291..d9f940d23 100644
--- a/lib/src/entrypoint.dart
+++ b/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) {
diff --git a/lib/src/executable.dart b/lib/src/executable.dart
index 5d0e7ba37..8a73f95eb 100644
--- a/lib/src/executable.dart
+++ b/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;
diff --git a/lib/src/global_packages.dart b/lib/src/global_packages.dart
index 4b5b9cf61..1f5dcde67 100644
--- a/lib/src/global_packages.dart
+++ b/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
diff --git a/lib/src/http.dart b/lib/src/http.dart
index 6d79d27ee..c97292979 100644
--- a/lib/src/http.dart
+++ b/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,
diff --git a/lib/src/ignore.dart b/lib/src/ignore.dart
index 75c0f1f08..0b9b1fca3 100644
--- a/lib/src/ignore.dart
+++ b/lib/src/ignore.dart
@@ -52,8 +52,8 @@ 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
@@ -61,12 +61,12 @@ final class Ignore {
   ///
   /// 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';
diff --git a/lib/src/io.dart b/lib/src/io.dart
index f65919fa0..db1a9ab61 100644
--- a/lib/src/io.dart
+++ b/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.
diff --git a/lib/src/log.dart b/lib/src/log.dart
index ee39cda2e..f8864fb34 100644
--- a/lib/src/log.dart
+++ b/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');
diff --git a/lib/src/oauth2.dart b/lib/src/oauth2.dart
index 9a116ef43..a8d36e311 100644
--- a/lib/src/oauth2.dart
+++ b/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
diff --git a/lib/src/progress.dart b/lib/src/progress.dart
index ad5d178a8..797679eb5 100644
--- a/lib/src/progress.dart
+++ b/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();
 
diff --git a/lib/src/pubspec.dart b/lib/src/pubspec.dart
index a90c51841..bf54497bf 100644
--- a/lib/src/pubspec.dart
+++ b/lib/src/pubspec.dart
@@ -357,7 +357,7 @@ class Pubspec extends PubspecBase {
   /// contents.
   ///
   /// If [expectedName] is passed and the pubspec doesn't have a matching name
-  /// field, this will throw a [PubspecError].
+  /// field, this will throw an [ApplicationException].
   ///
   /// [location] is the location from which this pubspec was loaded.
   Pubspec.fromMap(
@@ -652,9 +652,9 @@ Map<String, PackageRange> _parseDependencies(
 
 /// Parses [node] to a [VersionConstraint].
 ///
-/// If or [defaultUpperBoundConstraint] is specified then it will be set as the
-/// max constraint if the original constraint doesn't have an upper bound and it
-/// is compatible with [defaultUpperBoundConstraint].
+/// `null` is interpreted as [VersionConstraint.any].
+///
+/// A String is parsed with [VersionConstraint.parse].
 VersionConstraint _parseVersionConstraint(
   YamlNode? node,
   String? packageName,
diff --git a/lib/src/pubspec_utils.dart b/lib/src/pubspec_utils.dart
index 316312403..0e84c549d 100644
--- a/lib/src/pubspec_utils.dart
+++ b/lib/src/pubspec_utils.dart
@@ -129,10 +129,10 @@ VersionConstraint stripUpperBound(VersionConstraint constraint) {
 ///
 /// Will use just the constraint for dependencies hosted at the default host.
 ///
-/// Relative paths will be relative to [relativeEntrypoint].
+/// Relative paths will be relative to the directory of [receivingPackage].
 ///
 /// The syntax used for hosted will depend on the language version of
-/// [relativeEntrypoint]
+/// [receivingPackage].
 Object pubspecDescription(
   PackageRange range,
   SystemCache cache,
diff --git a/lib/src/rate_limited_scheduler.dart b/lib/src/rate_limited_scheduler.dart
index 0480b8219..6cb03b917 100644
--- a/lib/src/rate_limited_scheduler.dart
+++ b/lib/src/rate_limited_scheduler.dart
@@ -20,7 +20,7 @@ import 'package:pool/pool.dart';
 ///
 /// The operation will run in the [Zone] that the task was in when enqueued.
 ///
-/// If a task if [preschedule]d and later [schedule]d before the operation is
+/// If a task if `preschedule`d and later [schedule]d before the operation is
 /// started, the task will go in front of the queue with the zone of the
 /// [schedule] operation.
 ///
diff --git a/lib/src/solver/package_lister.dart b/lib/src/solver/package_lister.dart
index c38d30018..b8f5ccab2 100644
--- a/lib/src/solver/package_lister.dart
+++ b/lib/src/solver/package_lister.dart
@@ -388,7 +388,7 @@ class PackageLister {
   /// Returns the first and last indices in [_versions] of the contiguous set of
   /// versions whose pubspecs match [match].
   ///
-  /// Assumes [match] returns true for the pubspec whose version is at [index].
+  /// Assumes [match] returns true for the pubspec whose version is at [start].
   Future<(int firstIndex, int lastIndex)> _findBounds(
     int start,
     bool Function(Pubspec) match,
diff --git a/lib/src/solver/partial_solution.dart b/lib/src/solver/partial_solution.dart
index 466f22dba..90b869c56 100644
--- a/lib/src/solver/partial_solution.dart
+++ b/lib/src/solver/partial_solution.dart
@@ -164,9 +164,9 @@ class PartialSolution {
     throw StateError('[BUG] $term is not satisfied.');
   }
 
-  /// Returns whether `this` satisfies [other].
+  /// Returns whether `this` satisfies [term].
   ///
-  /// That is, whether [other] must be true given the assignments in this
+  /// That is, whether [term] must be true given the assignments in this
   /// partial solution.
   bool satisfies(Term term) => relation(term) == SetRelation.subset;
 
diff --git a/lib/src/solver/report.dart b/lib/src/solver/report.dart
index b16d70651..880fdf23c 100644
--- a/lib/src/solver/report.dart
+++ b/lib/src/solver/report.dart
@@ -332,8 +332,7 @@ $contentHashesDocumentationUrl
   /// Reports the results of the upgrade on the package named [name].
   ///
   /// If [alwaysShow] is true, the package is reported even if it didn't change,
-  /// regardless of [_type]. If [highlightOverride] is true (or absent), writes
-  /// "(override)" next to overridden packages.
+  /// regardless of [_type].
   ///
   /// Returns true if the package had changed.
   Future<bool> _reportPackage(
diff --git a/lib/src/solver/version_solver.dart b/lib/src/solver/version_solver.dart
index 49153a3ff..a77d2c119 100644
--- a/lib/src/solver/version_solver.dart
+++ b/lib/src/solver/version_solver.dart
@@ -232,12 +232,13 @@ class VersionSolver {
     return unsatisfied.package.name;
   }
 
-  /// Given an [incompatibility] that's satisfied by [_solution], [conflict
-  /// resolution][] constructs a new incompatibility that encapsulates the root
-  /// cause of the conflict and backtracks [_solution] until the new
+  /// Given an [incompatibility] that's satisfied by [_solution],
+  /// [conflict resolution][] constructs a new incompatibility that encapsulates
+  /// the root cause of the conflict and backtracks [_solution] until the new
   /// incompatibility will allow [_propagate] to deduce new assignments.
   ///
-  /// [conflict resolution]: https://github.com/dart-lang/pub/tree/master/doc/solver.md#conflict-resolution
+  /// [conflict resolution]:
+  /// https://github.com/dart-lang/pub/tree/master/doc/solver.md#conflict-resolution
   ///
   /// Adds the new incompatibility to [_incompatibilities] and returns it.
   Incompatibility _resolveConflict(Incompatibility incompatibility) {
diff --git a/lib/src/source.dart b/lib/src/source.dart
index 45a89b488..0c3fe70cc 100644
--- a/lib/src/source.dart
+++ b/lib/src/source.dart
@@ -12,7 +12,6 @@ import 'language_version.dart';
 import 'lock_file.dart';
 import 'package_name.dart';
 import 'pubspec.dart';
-import 'source.dart' as src;
 import 'source/cached.dart';
 import 'source/git.dart';
 import 'source/hosted.dart';
@@ -88,8 +87,8 @@ abstract class Source {
 
   /// Parses a [PackageId] from a name and a serialized description.
   ///
-  /// This only accepts descriptions serialized using [serializeDescription]. It
-  /// should not be used with user-authored descriptions.
+  /// This should accept descriptions serialized using
+  /// [ResolvedDescription.serializeForLockfile].
   ///
   /// [containingDir] is the path to the directory lockfile where this
   /// description appears. It may be `null` if the description is coming from
@@ -115,7 +114,7 @@ abstract class Source {
   /// downloaded).
   ///
   /// By default, this assumes that each description has a single version and
-  /// uses [describe] to get that version.
+  /// uses [SystemCache.describe] to get that version.
   Future<List<PackageId>> doGetVersions(
     PackageRef ref,
     Duration? maxAge,
@@ -143,7 +142,7 @@ abstract class Source {
   ///
   /// For sources that have only one version for a given [PackageRef], this may
   /// return a pubspec with a different version than that specified by [id]. If
-  /// they do, [describe] will throw a [PackageNotFoundException].
+  /// they do, [SystemCache.describe] will throw a [PackageNotFoundException].
   ///
   /// This may be called for packages that have not yet been downloaded during
   /// the version resolution process.
@@ -215,7 +214,7 @@ abstract class Description {
 /// to lock down a specific version.
 ///
 /// This is currently only relevant for the [GitSource] that resolves the
-/// [src.Description.ref] to a specific commit id in [GitSource.doGetVersions].
+/// [GitDescription.ref] to a specific commit id in [GitSource.doGetVersions].
 ///
 /// This is the information that goes into a `pubspec.lock` file together with
 /// a version number (that is represented by a [PackageId].
@@ -226,7 +225,7 @@ abstract class ResolvedDescription {
   /// When a [LockFile] is serialized, it uses this method to get the
   /// [description] in the right format.
   ///
-  /// [containingPath] is the containing directory of the root package.
+  /// [containingDir] is the containing directory of the root package.
   Object? serializeForLockfile({required String? containingDir});
 
   /// Converts `this` into a human-friendly form to show the user.
diff --git a/lib/src/source/cached.dart b/lib/src/source/cached.dart
index a83f96d64..ad7de0030 100644
--- a/lib/src/source/cached.dart
+++ b/lib/src/source/cached.dart
@@ -14,13 +14,12 @@ import '../pubspec.dart';
 import '../source.dart';
 import '../system_cache.dart';
 
-/// Base class for a [BoundSource] that installs packages into pub's
-/// [SystemCache].
+/// Base class for a [Source] that installs packages into pub's [SystemCache].
 ///
-/// A source should be cached if it requires network access to retrieve
-/// packages or the package needs to be "frozen" at the point in time that it's
-/// installed. (For example, Git packages are cached because installing from
-/// the same repo over time may yield different commits.)
+/// A source should be cached if it requires network access to retrieve packages
+/// or the package needs to be "frozen" at the point in time that it's
+/// installed. (For example, Git packages are cached because installing from the
+/// same repo over time may yield different commits.)
 abstract class CachedSource extends Source {
   /// If [id] is already in the system cache, just loads it from there.
   ///
@@ -76,7 +75,7 @@ abstract class CachedSource extends Source {
 
 /// The result of repairing a single cache entry.
 class RepairResult {
-  /// `true` if [package] was repaired successfully.
+  /// `true` if [packageName] was repaired successfully.
   /// `false` if something failed during the repair.
   ///
   /// When something goes wrong the package is attempted removed from
diff --git a/lib/src/source/git.dart b/lib/src/source/git.dart
index da42afb25..747d49495 100644
--- a/lib/src/source/git.dart
+++ b/lib/src/source/git.dart
@@ -251,7 +251,8 @@ class GitSource extends CachedSource {
     });
   }
 
-  /// Lists the file as it is represented at the revision of [description].
+  /// Lists the file as it is represented at the revision of
+  /// [resolvedDescription].
   ///
   /// Assumes that revision is present in the cache already (can be done with
   /// [_ensureRevision]).
@@ -677,9 +678,6 @@ class GitSource extends CachedSource {
   /// out the working tree, but instead makes the repository a local mirror of
   /// the remote repository. See the manpage for `git clone` for more
   /// information.
-  ///
-  /// If [shallow] is true, creates a shallow clone that contains no history
-  /// for the repository.
   Future<void> _clone(
     String from,
     String to, {
diff --git a/lib/src/source/hosted.dart b/lib/src/source/hosted.dart
index 5a91eb3a8..ef39e4070 100644
--- a/lib/src/source/hosted.dart
+++ b/lib/src/source/hosted.dart
@@ -1154,11 +1154,6 @@ class HostedSource extends CachedSource {
   ///
   /// Validates that the content hash of [id] corresponds to what is already in
   /// cache, if not the file is redownloaded.
-  ///
-  /// If [allowOutdatedHashChecks] is `true` we use a cached version listing
-  /// response if present instead of probing the server. Not probing allows for
-  /// `pub get` with a filled cache to be a fast case that doesn't require any
-  /// new version-listings.
   @override
   Future<DownloadPackageResult> downloadToSystemCache(
     PackageId id,
@@ -1446,8 +1441,8 @@ class HostedSource extends CachedSource {
   ) =>
       _download(id, destPath, cache);
 
-  /// Downloads package [package] at [version] from the archive_url and unpacks
-  /// it into [destPath].
+  /// Downloads package [id] from the archive_url and unpacks it into
+  /// [destPath].
   ///
   /// If there is no archive_url, try to fetch it from
   /// `$server/packages/$package/versions/$version.tar.gz` where server comes
@@ -1747,7 +1742,7 @@ See $contentHashesDocumentationUrl.
   }
 
   /// Enables speculative prefetching of dependencies of packages queried with
-  /// [getVersions].
+  /// [doGetVersions].
   Future<T> withPrefetching<T>(Future<T> Function() callback) async {
     return await _scheduler.withPrescheduling((preschedule) async {
       return await runZoned(
@@ -1761,7 +1756,7 @@ See $contentHashesDocumentationUrl.
   static const _prefetchingKey = #_prefetch;
 }
 
-/// The [PackageName.description] for a [HostedSource], storing the
+/// The [PackageRef.description] for a [HostedSource], storing the
 /// [packageName] and resolved [url] of the package server.
 class HostedDescription extends Description {
   final String packageName;
diff --git a/lib/src/system_cache.dart b/lib/src/system_cache.dart
index dc6e94904..7bedffcbf 100644
--- a/lib/src/system_cache.dart
+++ b/lib/src/system_cache.dart
@@ -213,11 +213,6 @@ Consider setting the `PUB_CACHE` variable manually.
   ///
   /// [id] must refer to a cached package.
   ///
-  /// If [allowOutdatedHashChecks] is `true` we use a cached version listing
-  /// response if present instead of probing the server. Not probing allows for
-  /// `pub get` with a filled cache to be a fast case that doesn't require any
-  /// new version-listings.
-  ///
   /// Returns [id] with an updated [ResolvedDescription], this can be different
   /// if the content-hash changed while downloading.
   Future<DownloadPackageResult> downloadPackage(PackageId id) async {
diff --git a/test/descriptor.dart b/test/descriptor.dart
index cee394d4f..ab991d385 100644
--- a/test/descriptor.dart
+++ b/test/descriptor.dart
@@ -185,13 +185,13 @@ Descriptor gitPackageRepoCacheDir(String name) =>
 /// versions are expected to be downloaded.
 ///
 /// If [port] is passed, it's used as the port number of the local hosted server
-/// that this cache represents. It defaults to [globalServer.port].
+/// that this cache represents. It defaults to `globalServer.port`.
 ///
 /// If [includePubspecs] is `true`, then pubspecs will be created for each
 /// package. Defaults to `false` so that the contents of pubspecs are not
 /// validated since they will often lack the dependencies section that the
 /// real pubspec being compared against has. You usually only need to pass
-/// `true` for this if you plan to call [create] on the resulting descriptor.
+/// `true` for this if you plan to call `create()` on the resulting descriptor.
 Descriptor cacheDir(
   Map<String, dynamic> packages, {
   int? port,
@@ -216,7 +216,7 @@ Descriptor cacheDir(
 /// downloaded from the mock package server.
 ///
 /// If [port] is passed, it's used as the port number of the local hosted server
-/// that this cache represents. It defaults to [globalServer.port].
+/// that this cache represents. It defaults to `globalServer.port`.
 Descriptor hostedCache(Iterable<Descriptor> contents, {int? port}) {
   return dir(hostedCachePath(port: port), contents);
 }
@@ -225,7 +225,7 @@ Descriptor hostedCache(Iterable<Descriptor> contents, {int? port}) {
 /// packages downloaded from the mock package server.
 ///
 /// If [port] is passed, it's used as the port number of the local hosted server
-/// that this cache represents. It defaults to [globalServer.port].
+/// that this cache represents. It defaults to `globalServer.port`.
 Descriptor hostedHashesCache(Iterable<Descriptor> contents, {int? port}) {
   return dir(cachePath, [
     dir(
@@ -314,10 +314,10 @@ DirectoryDescriptor appDir({Map? dependencies, Map<String, Object>? pubspec}) =>
 
 /// Describes a `.dart_tools/package_config.json` file.
 ///
-/// [dependencies] is a list of packages included in the file.
+/// [packages] is a list of packages included in the file.
 ///
 /// Validation checks that the `.dart_tools/package_config.json` file exists,
-/// has the expected entries (one per key in [dependencies]), each with a path
+/// has the expected entries (one per key in [packages]), each with a path
 /// that matches the `rootUri` of that package.
 Descriptor packageConfigFile(
   List<PackageConfigEntry> packages, {
diff --git a/test/descriptor/tar.dart b/test/descriptor/tar.dart
index f8570e548..954a75aca 100644
--- a/test/descriptor/tar.dart
+++ b/test/descriptor/tar.dart
@@ -19,7 +19,7 @@ class TarFileDescriptor extends FileDescriptor {
         super.protected();
 
   /// Creates the files and directories within this tar file, then archives
-  /// them, compresses them, and saves the result to [parentDir].
+  /// them, compresses them, and saves the result to [parent].
   @override
   Future create([String? parent]) {
     return withTempDir((tempDir) async {
diff --git a/test/embedding/ensure_pubspec_resolved.dart b/test/embedding/ensure_pubspec_resolved.dart
index 8e06a5982..37dc9843f 100644
--- a/test/embedding/ensure_pubspec_resolved.dart
+++ b/test/embedding/ensure_pubspec_resolved.dart
@@ -526,10 +526,6 @@ Future<void> _implicitPubGet(
 }
 
 /// Ensures that pub doesn't require "dart pub get" for the current package.
-///
-/// If [runDeps] is false, `pub deps` isn't included in the test. This is
-/// sometimes not desirable, since it uses slightly stronger checks for pubspec
-/// and lockfile consistency.
 Future<void> _noImplicitPubGet({
   Map<String, String?>? environment,
 }) async {
diff --git a/test/package_server.dart b/test/package_server.dart
index 2b5993019..7967aa4b2 100644
--- a/test/package_server.dart
+++ b/test/package_server.dart
@@ -333,8 +333,7 @@ class PackageServer {
   static final defaultAdvisoriesUpdated =
       DateTime.fromMicrosecondsSinceEpoch(0);
 
-  /// Add a security advisory which affects [affectedVersions] versions of
-  /// package [packageName].
+  /// Add a security advisory which affects versions in [affectedPackages].
   void addAdvisory({
     required String advisoryId,
     String? displayUrl,
diff --git a/test/test_pub.dart b/test/test_pub.dart
index bdc36cc3e..616590f9a 100644
--- a/test/test_pub.dart
+++ b/test/test_pub.dart
@@ -700,7 +700,7 @@ Future<void> createLockFile(
   ]).create();
 }
 
-/// Creates a lock file for [sources] without running `pub get`.
+/// Creates a lock file without running `pub get`.
 ///
 /// [sandbox] is a list of path dependencies to be found in the sandbox
 /// directory.
@@ -1017,7 +1017,7 @@ Future<PackageServer> startPackageServer() async {
   return server;
 }
 
-/// Create temporary folder 'bin/' containing a 'git' script in [sandbox]
+/// Create temporary folder 'bin/' containing a 'git' script in [d.sandbox]
 /// By adding the bin/ folder to the search `$PATH` we can prevent `pub` from
 /// detecting the installed 'git' binary and we can test that it prints
 /// a useful error message.
diff --git a/tool/extract_all_pub_dev.dart b/tool/extract_all_pub_dev.dart
index 50e716814..e140f4881 100644
--- a/tool/extract_all_pub_dev.dart
+++ b/tool/extract_all_pub_dev.dart
@@ -3,7 +3,7 @@
 // BSD-style license that can be found in the LICENSE file.
 
 /// This is a manual test that can be run to test the .tar.gz decoding.
-/// It will save progress in [statusFileName] such that it doesn't have to be
+/// It will save progress in `statusFileName` such that it doesn't have to be
 /// finished in a single run.
 library;