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;