Fix violations of comment_references lint (#4348)
diff --git a/analysis_options.yaml b/analysis_options.yaml
index c1d8ab7..c820ffe 100644
--- a/analysis_options.yaml
+++ b/analysis_options.yaml
@@ -3,7 +3,6 @@
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 412e3f4..2b4e835 100644
--- a/lib/src/authentication/client.dart
+++ b/lib/src/authentication/client.dart
@@ -17,7 +17,7 @@
/// 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 6199c5f..87ac45b 100644
--- a/lib/src/command/add.dart
+++ b/lib/src/command/add.dart
@@ -369,8 +369,8 @@
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 @@
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 @@
/// 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 904a4ac..19235b2 100644
--- a/lib/src/command/outdated.dart
+++ b/lib/src/command/outdated.dart
@@ -408,7 +408,7 @@
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 @@
}
}
-/// 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 1ed734f..f36fc83 100644
--- a/lib/src/dart.dart
+++ b/lib/src/dart.dart
@@ -38,9 +38,8 @@
/// 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 e2b2c52..d9f940d 100644
--- a/lib/src/entrypoint.dart
+++ b/lib/src/entrypoint.dart
@@ -324,7 +324,7 @@
/// 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 @@
/// 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 @@
});
}
- /// 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 @@
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 @@
}
}
- /// 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 @@
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 5d0e7ba..8a73f95 100644
--- a/lib/src/executable.dart
+++ b/lib/src/executable.dart
@@ -30,17 +30,17 @@
];
}
-/// 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 @@
/// * 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 @@
);
}
- /// 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 4b5b9cf..1f5dcde 100644
--- a/lib/src/global_packages.dart
+++ b/lib/src/global_packages.dart
@@ -81,8 +81,6 @@
/// 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 @@
);
}
- /// 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 @@
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 6d79d27..c972929 100644
--- a/lib/src/http.dart
+++ b/lib/src/http.dart
@@ -425,7 +425,7 @@
/// 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 @@
/// 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 75c0f1f..0b9b1fc 100644
--- a/lib/src/ignore.dart
+++ b/lib/src/ignore.dart
@@ -52,8 +52,8 @@
/// 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 @@
///
/// 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 @@
/// }
/// ```
///
- /// [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 @@
}
/// 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 f65919f..db1a9ab 100644
--- a/lib/src/io.dart
+++ b/lib/src/io.dart
@@ -105,8 +105,8 @@
/// 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 @@
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 ee39cda..f8864fb 100644
--- a/lib/src/log.dart
+++ b/lib/src/log.dart
@@ -43,8 +43,6 @@
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 9a116ef..a8d36e3 100644
--- a/lib/src/oauth2.dart
+++ b/lib/src/oauth2.dart
@@ -738,7 +738,7 @@
/// 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 ad5d178..797679e 100644
--- a/lib/src/progress.dart
+++ b/lib/src/progress.dart
@@ -30,8 +30,8 @@
/// 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 a90c518..bf54497 100644
--- a/lib/src/pubspec.dart
+++ b/lib/src/pubspec.dart
@@ -357,7 +357,7 @@
/// 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 @@
/// 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 3163124..0e84c54 100644
--- a/lib/src/pubspec_utils.dart
+++ b/lib/src/pubspec_utils.dart
@@ -129,10 +129,10 @@
///
/// 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 0480b82..6cb03b9 100644
--- a/lib/src/rate_limited_scheduler.dart
+++ b/lib/src/rate_limited_scheduler.dart
@@ -20,7 +20,7 @@
///
/// 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 c38d300..b8f5cca 100644
--- a/lib/src/solver/package_lister.dart
+++ b/lib/src/solver/package_lister.dart
@@ -388,7 +388,7 @@
/// 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 466f22d..90b869c 100644
--- a/lib/src/solver/partial_solution.dart
+++ b/lib/src/solver/partial_solution.dart
@@ -164,9 +164,9 @@
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 b16d706..880fdf2 100644
--- a/lib/src/solver/report.dart
+++ b/lib/src/solver/report.dart
@@ -332,8 +332,7 @@
/// 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 49153a3..a77d2c1 100644
--- a/lib/src/solver/version_solver.dart
+++ b/lib/src/solver/version_solver.dart
@@ -232,12 +232,13 @@
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 45a89b4..0c3fe70 100644
--- a/lib/src/source.dart
+++ b/lib/src/source.dart
@@ -12,7 +12,6 @@
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 @@
/// 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 @@
/// 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 @@
///
/// 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 @@
/// 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 @@
/// 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 a83f96d..ad7de00 100644
--- a/lib/src/source/cached.dart
+++ b/lib/src/source/cached.dart
@@ -14,13 +14,12 @@
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 @@
/// 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 da42afb..747d494 100644
--- a/lib/src/source/git.dart
+++ b/lib/src/source/git.dart
@@ -251,7 +251,8 @@
});
}
- /// 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 @@
/// 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 5a91eb3..ef39e40 100644
--- a/lib/src/source/hosted.dart
+++ b/lib/src/source/hosted.dart
@@ -1154,11 +1154,6 @@
///
/// 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 @@
) =>
_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 @@
}
/// 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 @@
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 dc6e949..7bedffc 100644
--- a/lib/src/system_cache.dart
+++ b/lib/src/system_cache.dart
@@ -213,11 +213,6 @@
///
/// [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 cee394d..ab991d3 100644
--- a/test/descriptor.dart
+++ b/test/descriptor.dart
@@ -185,13 +185,13 @@
/// 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 @@
/// 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 @@
/// 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 @@
/// 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 f8570e5..954a75a 100644
--- a/test/descriptor/tar.dart
+++ b/test/descriptor/tar.dart
@@ -19,7 +19,7 @@
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 8e06a59..37dc984 100644
--- a/test/embedding/ensure_pubspec_resolved.dart
+++ b/test/embedding/ensure_pubspec_resolved.dart
@@ -526,10 +526,6 @@
}
/// 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 2b59930..7967aa4 100644
--- a/test/package_server.dart
+++ b/test/package_server.dart
@@ -333,8 +333,7 @@
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 bdc36cc..616590f 100644
--- a/test/test_pub.dart
+++ b/test/test_pub.dart
@@ -700,7 +700,7 @@
]).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 @@
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 50e7168..e140f48 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;
