diff --git a/bin/pub.dart b/bin/pub.dart
index a10c09b62513a94192cd5bac1aaf07026f37b7c7..94d5ab08a1b271b047c214b4f5c81ab287f6d50b 100644
--- a/bin/pub.dart
+++ b/bin/pub.dart
@@ -199,8 +199,10 @@ Future invokeCommand(String cacheDir, ArgResults mainOptions) {
});
}
-/// Checks that pub is running on a supported platform. If it isn't, it prints
-/// an error message and exits. Completes when the validation is done.
+/// Checks that pub is running on a supported platform.
+///
+/// If it isn't, it prints an error message and exits. Completes when the
+/// validation is done.
Future validatePlatform() {
return syncFuture(() {
if (Platform.operatingSystem != 'windows') return null;
diff --git a/lib/src/barback/web_socket_api.dart b/lib/src/barback/web_socket_api.dart
index dcfe4c8778e0e6f49e9690bb5b1b5937664dab6b..a580a2c60c0f3b94f9499346fd46e8b5f080c24a 100644
--- a/lib/src/barback/web_socket_api.dart
+++ b/lib/src/barback/web_socket_api.dart
@@ -299,7 +299,6 @@ class WebSocketApi {
}
}
-
/// The pub-specific JSON RPC error codes.
class _Error {
/// The specified directory is not being served.
diff --git a/lib/src/command.dart b/lib/src/command.dart
index 6592736dc552a1c7949d762044df6cb7e06bfcb3..660693bf872ac5f569a9ecd8f35477bc81258356 100644
--- a/lib/src/command.dart
+++ b/lib/src/command.dart
@@ -134,8 +134,10 @@ abstract class PubCommand {
/// parsed after a non-option argument is parsed.
bool get allowTrailingOptions => true;
- /// Alternate names for this command. These names won't be used in the
- /// documentation, but they will work when invoked on the command line.
+ /// Alternate names for this command.
+ ///
+ /// These names won't be used in the documentation, but they will work when
+ /// invoked on the command line.
final aliases = const <String>[];
/// The [ArgParser] for this command.
diff --git a/lib/src/dart.dart b/lib/src/dart.dart
index 9a8510568c66d70f3fd0a814d5500cdcf78187c7..9a26e1ceb4fc25922e35a750e1fe33a181754429 100644
--- a/lib/src/dart.dart
+++ b/lib/src/dart.dart
@@ -18,8 +18,8 @@ import '../../../compiler/implementation/filenames.dart'
import '../../asset/dart/serialize.dart';
import 'io.dart';
-import 'utils.dart';
+import 'utils.dart';
/// Interface to communicate with dart2js.
///
/// This is basically an amalgamation of dart2js's
diff --git a/lib/src/entrypoint.dart b/lib/src/entrypoint.dart
index ce4d11f614433e0d5ebc2f772e82ceb2d993c0f2..ef8d1d21aff6849d42c970794434a95972b7d334 100644
--- a/lib/src/entrypoint.dart
+++ b/lib/src/entrypoint.dart
@@ -19,6 +19,8 @@ import 'source/cached.dart';
import 'system_cache.dart';
import 'utils.dart';
+/// The context surrounding the root package pub is operating on.
+///
/// Pub operates over a directed graph of dependencies that starts at a root
/// "entrypoint" package. This is typically the package where the current
/// working directory is located. An entrypoint knows the [root] package it is
@@ -147,7 +149,9 @@ class Entrypoint {
}
/// Loads the list of concrete package versions from the `pubspec.lock`, if it
- /// exists. If it doesn't, this completes to an empty [LockFile].
+ /// exists.
+ ///
+ /// If it doesn't, this completes to an empty [LockFile].
LockFile loadLockFile() {
if (!lockFileExists) return new LockFile.empty();
return new LockFile.load(lockFilePath, cache.sources);
@@ -243,8 +247,10 @@ class Entrypoint {
}
/// Loads the package graph for the application and all of its transitive
- /// dependencies. Before loading makes sure the lockfile and dependencies are
- /// installed and up to date.
+ /// dependencies.
+ ///
+ /// Before loading, makes sure the lockfile and dependencies are installed
+ /// and up to date.
Future<PackageGraph> loadPackageGraph() {
return _ensureLockFileIsUpToDate().then((_) {
var lockFile = loadLockFile();
diff --git a/lib/src/error_group.dart b/lib/src/error_group.dart
index 52a284c8049a422e7cf291a2f8c864d4b9ab8167..c479a24e9969eefe12e8d788c4520d482bcb6b6a 100644
--- a/lib/src/error_group.dart
+++ b/lib/src/error_group.dart
@@ -7,9 +7,11 @@ library pub.error_group;
import 'dart:async';
/// An [ErrorGroup] entangles the errors of multiple [Future]s and [Stream]s
-/// with one another. This allows APIs to expose multiple [Future]s and
-/// [Stream]s that have identical error conditions without forcing API consumers
-/// to attach error handling to objects they don't care about.
+/// with one another.
+///
+/// This allows APIs to expose multiple [Future]s and [Stream]s that have
+/// identical error conditions without forcing API consumers to attach error
+/// handling to objects they don't care about.
///
/// To use an [ErrorGroup], register [Future]s and [Stream]s with it using
/// [registerFuture] and [registerStream]. These methods return wrapped versions
@@ -40,9 +42,10 @@ class ErrorGroup {
/// The [Completer] for [done].
final _doneCompleter = new Completer();
- /// The underlying [Future] for [done]. We need to be able to access it
- /// internally as an [_ErrorGroupFuture] so we can check if it has listeners
- /// and signal errors on it.
+ /// The underlying [Future] for [done].
+ ///
+ /// We need to be able to access it internally as an [_ErrorGroupFuture] so
+ /// we can check if it has listeners and signal errors on it.
_ErrorGroupFuture _done;
/// Returns a [Future] that completes successully when all members of [this]
@@ -58,8 +61,9 @@ class ErrorGroup {
this._done = new _ErrorGroupFuture(this, _doneCompleter.future);
}
- /// Registers a [Future] as a member of [this]. Returns a wrapped version of
- /// [future] that should be used in its place.
+ /// Registers a [Future] as a member of [this].
+ ///
+ /// Returns a wrapped version of [future] that should be used in its place.
///
/// If all members of [this] have already completed successfully or with an
/// error, it's a [StateError] to try to register a new [Future].
@@ -74,9 +78,11 @@ class ErrorGroup {
return wrapped;
}
- /// Registers a [Stream] as a member of [this]. Returns a wrapped version of
- /// [stream] that should be used in its place. The returned [Stream] will be
- /// multi-subscription if and only if [stream] is.
+ /// Registers a [Stream] as a member of [this].
+ ///
+ /// Returns a wrapped version of [stream] that should be used in its place.
+ /// The returned [Stream] will be multi-subscription if and only if [stream]
+ /// is.
///
/// Since all errors in a group are passed to all members, the returned
/// [Stream] will automatically unsubscribe all its listeners when it
@@ -95,9 +101,10 @@ class ErrorGroup {
return wrapped;
}
- /// Sends [error] to all members of [this]. Like errors that come from
- /// members, this will only be passed to the top-level error handler if no
- /// members have listeners.
+ /// Sends [error] to all members of [this].
+ ///
+ /// Like errors that come from members, this will only be passed to the
+ /// top-level error handler if no members have listeners.
///
/// If all members of [this] have already completed successfully or with an
/// error, it's a [StateError] to try to signal an error.
@@ -109,8 +116,10 @@ class ErrorGroup {
_signalError(error, stackTrace);
}
- /// Signal an error internally. This is just like [signalError], but instead
- /// of throwing an error if [this] is complete, it just does nothing.
+ /// Signal an error internally.
+ ///
+ /// This is just like [signalError], but instead of throwing an error if
+ /// [this] is complete, it just does nothing.
void _signalError(var error, [StackTrace stackTrace]) {
if (_isDone) return;
@@ -150,8 +159,10 @@ class ErrorGroup {
}
/// A [Future] wrapper that keeps track of whether it's been completed and
-/// whether it has any listeners. It also notifies its parent [ErrorGroup] when
-/// it completes successfully or receives an error.
+/// whether it has any listeners.
+///
+/// It also notifies its parent [ErrorGroup] when it completes successfully or
+/// receives an error.
class _ErrorGroupFuture implements Future {
/// The parent [ErrorGroup].
final ErrorGroup _group;
@@ -216,8 +227,10 @@ class _ErrorGroupFuture implements Future {
// When this is fixed, this class will need to prevent such errors from being
// top-leveled.
/// A [Stream] wrapper that keeps track of whether it's been completed and
-/// whether it has any listeners. It also notifies its parent [ErrorGroup] when
-/// it completes successfully or receives an error.
+/// whether it has any listeners.
+///
+/// It also notifies its parent [ErrorGroup] when it completes successfully or
+/// receives an error.
class _ErrorGroupStream extends Stream {
/// The parent [ErrorGroup].
final ErrorGroup _group;
@@ -228,8 +241,10 @@ class _ErrorGroupStream extends Stream {
/// The underlying [StreamController] for [this].
final StreamController _controller;
- /// The controller's [Stream]. May be different than `_controller.stream` if
- /// the wrapped stream is a broadcasting stream.
+ /// The controller's [Stream].
+ ///
+ /// May be different than `_controller.stream` if the wrapped stream is a
+ /// broadcasting stream.
Stream _stream;
/// The [StreamSubscription] that connects the wrapped [Stream] to
diff --git a/lib/src/exit_codes.dart b/lib/src/exit_codes.dart
index a1683cd9c6b7784974c6872f96874af0fc5d4b91..ebe8e8deab8e584eb14f1a8156bb00fa404634ce 100644
--- a/lib/src/exit_codes.dart
+++ b/lib/src/exit_codes.dart
@@ -2,9 +2,11 @@
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.
-/// Exit code constants. From [the BSD sysexits manpage][manpage]. Not every
-/// constant here is used, even though some of the unused ones may be
-/// appropriate for errors encountered by pub.
+/// Exit code constants.
+///
+/// From [the BSD sysexits manpage][manpage]. Not every constant here is used,
+/// even though some of the unused ones may be appropriate for errors
+/// encountered by pub.
///
/// [manpage]: http://www.freebsd.org/cgi/man.cgi?query=sysexits
library pub.exit_codes;
diff --git a/lib/src/git.dart b/lib/src/git.dart
index e6f20cb269c15b9d6da290d7ab9772fffe932b02..5ba66b2ab4f3528044465bdb218f4f4cead9b989 100644
--- a/lib/src/git.dart
+++ b/lib/src/git.dart
@@ -38,8 +38,10 @@ bool get isInstalled {
}
bool _isInstalledCache;
-/// Run a git process with [args] from [workingDir]. Returns the stdout as a
-/// list of strings if it succeeded. Completes to an exception if it failed.
+/// Run a git process with [args] from [workingDir].
+///
+/// Returns the stdout as a list of strings if it succeeded. Completes to an
+/// exception if it failed.
Future<List<String>> run(List<String> args,
{String workingDir, Map<String, String> environment}) {
if (!isInstalled) {
diff --git a/lib/src/http.dart b/lib/src/http.dart
index 13f87afd91f1a69c231048551bc184439ac12aa9..24dbacbeafe66a7900549a8c3a022f463336431f 100644
--- a/lib/src/http.dart
+++ b/lib/src/http.dart
@@ -224,8 +224,10 @@ void handleJsonError(http.Response response) {
fail(errorMap['error']['message']);
}
-/// Parses a response body, assuming it's JSON-formatted. Throws a user-friendly
-/// error if the response body is invalid JSON, or if it's not a map.
+/// Parses a response body, assuming it's JSON-formatted.
+///
+/// Throws a user-friendly error if the response body is invalid JSON, or if
+/// it's not a map.
Map parseJsonResponse(http.Response response) {
var value;
try {
diff --git a/lib/src/io.dart b/lib/src/io.dart
index 52752b15209bb4c9875f646d6de35b0f33554695..ea6b19eb7801e78083e929f8b0440a6d84b8cdb8 100644
--- a/lib/src/io.dart
+++ b/lib/src/io.dart
@@ -36,17 +36,22 @@ final _descriptorPool = new Pool(32);
bool entryExists(String path) =>
dirExists(path) || fileExists(path) || linkExists(path);
-/// Returns whether [link] exists on the file system. This will return `true`
-/// for any symlink, regardless of what it points at or whether it's broken.
+/// Returns whether [link] exists on the file system.
+///
+/// This returns `true` for any symlink, regardless of what it points at or
+/// whether it's broken.
bool linkExists(String link) => new Link(link).existsSync();
-/// Returns whether [file] exists on the file system. This will return `true`
-/// for a symlink only if that symlink is unbroken and points to a file.
+/// Returns whether [file] exists on the file system.
+///
+/// This returns `true` for a symlink only if that symlink is unbroken and
+/// points to a file.
bool fileExists(String file) => new File(file).existsSync();
-/// 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.
+/// 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 doesn't require [pathString] to point to a path that exists on the
/// filesystem; nonexistent or unreadable path entries are treated as normal
@@ -125,8 +130,10 @@ String canonicalize(String pathString) {
}
/// Returns the transitive target of [link] (if A links to B which links to C,
-/// this will return C). If [link] is part of a symlink loop (e.g. A links to B
-/// which links back to A), this returns the path to the first repeated link (so
+/// this will return C).
+///
+/// If [link] is part of a symlink loop (e.g. A links to B which links back to
+/// A), this returns the path to the first repeated link (so
/// `transitiveTarget("A")` would return `"A"` and `transitiveTarget("A")` would
/// return `"B"`).
///
@@ -178,8 +185,10 @@ String writeBinaryFile(String file, List<int> contents) {
return file;
}
-/// Writes [stream] to a new file at path [file]. Will replace any file already
-/// at that path. Completes when the file is done being written.
+/// Writes [stream] to a new file at path [file].
+///
+/// Replaces any file already at that path. Completes when the file is done
+/// being written.
Future<String> createFileFromStream(Stream<List<int>> stream, String file) {
// TODO(nweiz): remove extra logging when we figure out the windows bot issue.
log.io("Creating $file from stream.");
@@ -192,9 +201,11 @@ Future<String> createFileFromStream(Stream<List<int>> stream, String file) {
});
}
-/// Copy all files in [files] to the directory [destination]. Their locations in
-/// [destination] will be determined by their relative location to [baseDir].
-/// Any existing files at those paths will be overwritten.
+/// Copies all files in [files] to the directory [destination].
+///
+/// Their locations in [destination] will be determined by their relative
+/// location to [baseDir]. Any existing files at those paths will be
+/// overwritten.
void copyFiles(Iterable<String> files, String baseDir, String destination) {
for (var file in files) {
var newPath = path.join(destination, path.relative(file, from: baseDir));
@@ -203,7 +214,7 @@ void copyFiles(Iterable<String> files, String baseDir, String destination) {
}
}
-/// Copy a file from [source] to [destination].
+/// Copies a file from [source] to [destination].
void copyFile(String source, String destination) {
writeBinaryFile(destination, readBinaryFile(source));
}
@@ -214,8 +225,9 @@ String createDir(String dir) {
return dir;
}
-/// Ensures that [dir] and all its parent directories exist. If they don't
-/// exist, creates them.
+/// Ensures that [dir] and all its parent directories exist.
+///
+/// If they don't exist, creates them.
String ensureDir(String dir) {
new Directory(dir).createSync(recursive: true);
return dir;
@@ -223,6 +235,7 @@ String ensureDir(String dir) {
/// Creates a temp directory in [dir], whose name will be [prefix] with
/// characters appended to it to make a unique name.
+///
/// Returns the path of the created directory.
String createTempDir(String base, String prefix) {
var tempDir = new Directory(base).createTempSync(prefix);
@@ -232,6 +245,7 @@ String createTempDir(String base, String prefix) {
/// Creates a temp directory in the system temp directory, whose name will be
/// 'pub_' with characters appended to it to make a unique name.
+///
/// Returns the path of the created directory.
String createSystemTempDir() {
var tempDir = Directory.systemTemp.createTempSync('pub_');
@@ -239,9 +253,11 @@ String createSystemTempDir() {
return tempDir.path;
}
-/// Lists the contents of [dir]. If [recursive] is `true`, lists subdirectory
-/// contents (defaults to `false`). If [includeHidden] is `true`, includes files
-/// and directories beginning with `.` (defaults to `false`).
+/// Lists the contents of [dir].
+///
+/// If [recursive] is `true`, lists subdirectory contents (defaults to
+/// `false`). If [includeHidden] is `true`, includes files and directories
+/// beginning with `.` (defaults to `false`).
///
/// Note that dart:io handles recursive symlinks in an unfortunate way. You
/// end up with two copies of every entity that is within the recursive loop.
@@ -266,11 +282,13 @@ List<String> listDir(String dir, {bool recursive: false,
return entities.map((entity) => entity.path).toList();
}
-/// Returns whether [dir] exists on the file system. This will return `true` for
-/// a symlink only if that symlink is unbroken and points to a directory.
+/// Returns whether [dir] exists on the file system.
+///
+/// This returns `true` for a symlink only if that symlink is unbroken and
+/// points to a directory.
bool dirExists(String dir) => new Directory(dir).existsSync();
-/// Try to resiliently perform [operation].
+/// Tries to resiliently perform [operation].
///
/// Some file system operations can intermittently fail on Windows because
/// other processes are locking a file. We've seen this with virus scanners
@@ -321,8 +339,9 @@ void _attempt(String description, void operation()) {
}
}
-/// Deletes whatever's at [path], whether it's a file, directory, or symlink. If
-/// it's a directory, it will be deleted recursively.
+/// Deletes whatever's at [path], whether it's a file, directory, or symlink.
+///
+/// If it's a directory, it will be deleted recursively.
void deleteEntry(String path) {
_attempt("delete entry", () {
if (linkExists(path)) {
@@ -338,8 +357,10 @@ void deleteEntry(String path) {
});
}
-/// "Cleans" [dir]. If that directory already exists, it will be deleted. Then a
-/// new empty directory will be created.
+/// "Cleans" [dir].
+///
+/// If that directory already exists, it is deleted. Then a new empty directory
+/// is created.
void cleanDir(String dir) {
if (entryExists(dir)) deleteEntry(dir);
ensureDir(dir);
@@ -359,8 +380,9 @@ void renameDir(String from, String to) {
});
}
-/// Creates a new symlink at path [symlink] that points to [target]. Returns a
-/// [Future] which completes to the path to the symlink file.
+/// Creates a new symlink at path [symlink] that points to [target].
+///
+/// Returns a [Future] which completes to the path to the symlink file.
///
/// If [relative] is true, creates a symlink with a relative path from the
/// symlink to the target. Otherwise, uses the [target] path unmodified.
@@ -389,8 +411,10 @@ void createSymlink(String target, String symlink,
}
/// Creates a new symlink that creates an alias at [symlink] that points to the
-/// `lib` directory of package [target]. If [target] does not have a `lib`
-/// directory, this shows a warning if appropriate and then does nothing.
+/// `lib` directory of package [target].
+///
+/// If [target] does not have a `lib` directory, this shows a warning if
+/// appropriate and then does nothing.
///
/// If [relative] is true, creates a symlink with a relative path from the
/// symlink to the target. Otherwise, uses the [target] path unmodified.
@@ -420,8 +444,9 @@ String assetPath(String target) {
}
}
-/// Returns the path to the root of the Dart repository. This will throw a
-/// [StateError] if it's called when running pub from the SDK.
+/// Returns the path to the root of the Dart repository.
+///
+/// This throws a [StateError] if it's called when running pub from the SDK.
String get repoRoot {
if (runningFromSdk) {
throw new StateError("Can't get the repo root from the SDK.");
@@ -434,9 +459,10 @@ String get repoRoot {
final Stream<String> stdinLines = streamToLines(
new ByteStream(Chain.track(stdin)).toStringStream());
-/// Displays a message and reads a yes/no confirmation from the user. Returns
-/// a [Future] that completes to `true` if the user confirms or `false` if they
-/// do not.
+/// Displays a message and reads a yes/no confirmation from the user.
+///
+/// Returns a [Future] that completes to `true` if the user confirms or `false`
+/// if they do not.
///
/// This will automatically append " (y/n)?" to the message, so [message]
/// should just be a fragment like, "Are you sure you want to proceed".
@@ -451,8 +477,9 @@ Future<bool> confirm(String message) {
.then((line) => new RegExp(r"^[yY]").hasMatch(line));
}
-/// Reads and discards all output from [stream]. Returns a [Future] that
-/// completes when the stream is closed.
+/// Reads and discards all output from [stream].
+///
+/// Returns a [Future] that completes when the stream is closed.
Future drainStream(Stream stream) {
return stream.fold(null, (x, y) {});
}
@@ -480,9 +507,10 @@ Pair<EventSink, Future> consumerToSink(StreamConsumer consumer) {
}
// TODO(nweiz): remove this when issue 7786 is fixed.
-/// Pipes all data and errors from [stream] into [sink]. When [stream] is done,
-/// the returned [Future] is completed and [sink] is closed if [closeSink] is
-/// true.
+/// Pipes all data and errors from [stream] into [sink].
+///
+/// When [stream] is done, the returned [Future] is completed and [sink] is
+/// closed if [closeSink] is true.
///
/// When an error occurs on [stream], that error is passed to [sink]. If
/// [cancelOnError] is true, [Future] will be completed successfully and no
@@ -506,6 +534,7 @@ Future store(Stream stream, EventSink sink,
}
/// Spawns and runs the process located at [executable], passing in [args].
+///
/// Returns a [Future] that will complete with the results of the process after
/// it has ended.
///
@@ -525,8 +554,10 @@ Future<PubProcessResult> runProcess(String executable, List<String> args,
});
}
-/// Spawns the process located at [executable], passing in [args]. Returns a
-/// [Future] that will complete with the [Process] once it's been started.
+/// Spawns the process located at [executable], passing in [args].
+///
+/// Returns a [Future] that will complete with the [Process] once it's been
+/// started.
///
/// The spawned process will inherit its parent's environment variables. If
/// [environment] is provided, that will be used to augment (not replace) the
@@ -575,6 +606,7 @@ class PubProcess {
Future<int> _exitCode;
/// The sink used for passing data to the process's standard input stream.
+ ///
/// Errors on this stream are surfaced through [stdinClosed], [stdout],
/// [stderr], and [exitCode], which are all members of an [ErrorGroup].
EventSink<List<int>> get stdin => _stdin;
@@ -638,9 +670,10 @@ class PubProcess {
_process.kill(signal);
}
-/// Calls [fn] with appropriately modified arguments. [fn] should have the same
-/// signature as [Process.start], except that the returned value may have any
-/// return type.
+/// Calls [fn] with appropriately modified arguments.
+///
+/// [fn] should have the same signature as [Process.start], except that the
+/// returned value may have any return type.
_doProcess(Function fn, String executable, List<String> args,
String workingDir, Map<String, String> environment) {
// TODO(rnystrom): Should dart:io just handle this?
@@ -701,10 +734,11 @@ Future timeout(Future input, int milliseconds, Uri url, String description) {
return completer.future;
}
-/// Creates a temporary directory and passes its path to [fn]. Once the [Future]
-/// returned by [fn] completes, the temporary directory and all its contents
-/// will be deleted. [fn] can also return `null`, in which case the temporary
-/// directory is deleted immediately afterwards.
+/// Creates a temporary directory and passes its path to [fn].
+///
+/// Once the [Future] returned by [fn] completes, the temporary directory and
+/// all its contents are deleted. [fn] can also return `null`, in which case
+/// the temporary directory is deleted immediately afterwards.
///
/// Returns a future that completes to the value that the future returned from
/// [fn] completes to.
@@ -725,8 +759,9 @@ Future<HttpServer> bindServer(String host, int port) {
return HttpServer.bind(host, port);
}
-/// Extracts a `.tar.gz` file from [stream] to [destination]. Returns whether
-/// or not the extraction was successful.
+/// Extracts a `.tar.gz` file from [stream] to [destination].
+///
+/// Returns whether or not the extraction was successful.
Future<bool> extractTarGz(Stream<List<int>> stream, String destination) {
log.fine("Extracting .tar.gz stream to $destination.");
@@ -807,10 +842,13 @@ Future<bool> _extractTarGzWindows(Stream<List<int>> stream,
});
}
-/// Create a .tar.gz archive from a list of entries. Each entry can be a
-/// [String], [Directory], or [File] object. The root of the archive is
-/// considered to be [baseDir], which defaults to the current working directory.
-/// Returns a [ByteStream] that will emit the contents of the archive.
+/// Create a .tar.gz archive from a list of entries.
+///
+/// Each entry can be a [String], [Directory], or [File] object. The root of
+/// the archive is considered to be [baseDir], which defaults to the current
+/// working directory.
+///
+/// Returns a [ByteStream] that emits the contents of the archive.
ByteStream createTarGz(List contents, {baseDir}) {
return new ByteStream(futureStream(syncFuture(() {
var buffer = new StringBuffer();
diff --git a/lib/src/log.dart b/lib/src/log.dart
index c5e626970f55b2aa39e7b6aecb2a4691bf5a736f..d364f8cb345d3c716ad243fdfcce7df57bcd7605 100644
--- a/lib/src/log.dart
+++ b/lib/src/log.dart
@@ -60,8 +60,9 @@ final _bold = getSpecial('\u001b[1m');
/// By default, [ERROR] and [WARNING] messages are printed to sterr. [MESSAGE]
/// messages are printed to stdout, and others are ignored.
class Level {
- /// An error occurred and an operation could not be completed. Usually shown
- /// to the user on stderr.
+ /// An error occurred and an operation could not be completed.
+ ///
+ /// Usually shown to the user on stderr.
static const ERROR = const Level._("ERR ");
/// Something unexpected happened, but the program was able to continue,
@@ -78,9 +79,11 @@ class Level {
/// Incremental output during pub's version constraint solver.
static const SOLVER = const Level._("SLVR");
- /// Fine-grained and verbose additional information. Can be used to provide
- /// program state context for other logs (such as what pub was doing when an
- /// IO operation occurred) or just more detail for an operation.
+ /// Fine-grained and verbose additional information.
+ ///
+ /// Used to provide program state context for other logs (such as what pub
+ /// was doing when an IO operation occurred) or just more detail for an
+ /// operation.
static const FINE = const Level._("FINE");
const Level._(this.name);
@@ -218,10 +221,11 @@ void write(Level level, message) {
if (_transcript != null) _transcript.add(entry);
}
-/// Logs an asynchronous IO operation. Logs [startMessage] before the operation
-/// starts, then when [operation] completes, invokes [endMessage] with the
-/// completion value and logs the result of that. Returns a future that
-/// completes after the logging is done.
+/// Logs an asynchronous IO operation.
+///
+/// Logs [startMessage] before the operation starts, then when [operation]
+/// completes, invokes [endMessage] with the completion value and logs the
+/// result of that. Returns a future that completes after the logging is done.
///
/// If [endMessage] is omitted, then logs "Begin [startMessage]" before the
/// operation and "End [startMessage]" after it.
diff --git a/lib/src/oauth2.dart b/lib/src/oauth2.dart
index ce344bbf546338b1fbc95d1738068d2b5dc35dba..8de110c00b55f60e55446e2ee1c54cc1e0289d67 100644
--- a/lib/src/oauth2.dart
+++ b/lib/src/oauth2.dart
@@ -24,8 +24,9 @@ export 'package:oauth2/oauth2.dart';
final _identifier = '818368855108-8grd2eg9tj9f38os6f1urbcvsq399u8n.apps.'
'googleusercontent.com';
-/// The pub client's OAuth2 secret. This isn't actually meant to be kept a
-/// secret.
+/// The pub client's OAuth2 secret.
+///
+/// This isn't actually meant to be kept a secret.
final _secret = 'SWeqj8seoJW0w7_CpEPFLX0K';
/// The URL to which the user will be directed to authorize the pub client to
@@ -40,8 +41,10 @@ final authorizationEndpoint = Uri.parse(
'&approval_prompt=force');
/// The URL from which the pub client will request an access token once it's
-/// been authorized by the user. This can be controlled externally by setting
-/// the _PUB_TEST_TOKEN_ENDPOINT environment variable.
+/// been authorized by the user.
+///
+/// This can be controlled externally by setting the `_PUB_TEST_TOKEN_ENDPOINT`
+/// environment variable.
Uri get tokenEndpoint {
var tokenEndpoint = Platform.environment['_PUB_TEST_TOKEN_ENDPOINT'];
if (tokenEndpoint != null) {
@@ -53,12 +56,16 @@ Uri get tokenEndpoint {
final _tokenEndpoint = Uri.parse('https://accounts.google.com/o/oauth2/token');
-/// The OAuth2 scopes that the pub client needs. Currently the client only needs
-/// the user's email so that the server can verify their identity.
+/// The OAuth2 scopes that the pub client needs.
+///
+/// Currently the client only needs the user's email so that the server can
+/// verify their identity.
final _scopes = ['https://www.googleapis.com/auth/userinfo.email'];
-/// An in-memory cache of the user's OAuth2 credentials. This should always be
-/// the same as the credentials file stored in the system cache.
+/// An in-memory cache of the user's OAuth2 credentials.
+///
+/// This should always be the same as the credentials file stored in the system
+/// cache.
Credentials _credentials;
/// Delete the cached credentials, if they exist.
@@ -101,8 +108,10 @@ Future withClient(SystemCache cache, Future fn(Client client)) {
});
}
-/// Gets a new OAuth2 client. If saved credentials are available, those are
-/// used; otherwise, the user is prompted to authorize the pub client.
+/// Gets a new OAuth2 client.
+///
+/// If saved credentials are available, those are used; otherwise, the user is
+/// prompted to authorize the pub client.
Future<Client> _getClient(SystemCache cache) {
return new Future.sync(() {
var credentials = _loadCredentials(cache);
@@ -116,8 +125,10 @@ Future<Client> _getClient(SystemCache cache) {
}
/// Loads the user's OAuth2 credentials from the in-memory cache or the
-/// filesystem if possible. If the credentials can't be loaded for any reason,
-/// the returned [Future] will complete to null.
+/// filesystem if possible.
+///
+/// If the credentials can't be loaded for any reason, the returned [Future]
+/// completes to `null`.
Credentials _loadCredentials(SystemCache cache) {
log.fine('Loading OAuth2 credentials.');
@@ -157,7 +168,8 @@ String _credentialsFile(SystemCache cache) =>
path.join(cache.rootDir, 'credentials.json');
/// Gets the user to authorize pub as a client of pub.dartlang.org via oauth2.
-/// Returns a Future that will complete to a fully-authorized [Client].
+///
+/// Returns a Future that completes to a fully-authorized [Client].
Future<Client> _authorize() {
var grant = new AuthorizationCodeGrant(
_identifier,
diff --git a/lib/src/package.dart b/lib/src/package.dart
index 8f6f61768b744c400cb11f580b7885ac9407918c..238744bce148e2577940fa83f6243c1c34e93b5c 100644
--- a/lib/src/package.dart
+++ b/lib/src/package.dart
@@ -72,10 +72,11 @@ class Package {
}
/// Returns the path to the README file at the root of the entrypoint, or null
- /// if no README file is found. If multiple READMEs are found, this uses the
- /// same conventions as pub.dartlang.org for choosing the primary one: the
- /// README with the fewest extensions that is lexically ordered first is
- /// chosen.
+ /// if no README file is found.
+ ///
+ /// If multiple READMEs are found, this uses the same conventions as
+ /// pub.dartlang.org for choosing the primary one: the README with the fewest
+ /// extensions that is lexically ordered first is chosen.
String get readmePath {
var readmes = listDir(dir).map(path.basename).
where((entry) => entry.contains(_README_REGEXP));
@@ -90,15 +91,18 @@ class Package {
}));
}
- /// Loads the package whose root directory is [packageDir]. [name] is the
- /// expected name of that package (e.g. the name given in the dependency), or
- /// `null` if the package being loaded is the entrypoint package.
+ /// Loads the package whose root directory is [packageDir].
+ ///
+ /// [name] is the expected name of that package (e.g. the name given in the
+ /// dependency), or `null` if the package being loaded is the entrypoint
+ /// package.
Package.load(String name, String packageDir, SourceRegistry sources)
: dir = packageDir,
pubspec = new Pubspec.load(packageDir, sources, expectedName: name);
- /// Constructs a package with the given pubspec. The package will have no
- /// directory associated with it.
+ /// Constructs a package with the given pubspec.
+ ///
+ /// The package will have no directory associated with it.
Package.inMemory(this.pubspec)
: dir = null;
@@ -107,9 +111,11 @@ class Package {
}
/// This is the private base class of [PackageRef], [PackageID], and
-/// [PackageDep]. It contains functionality and state that those classes share
-/// but is private so that from outside of this library, there is no type
-/// relationship between those three types.
+/// [PackageDep].
+///
+/// It contains functionality and state that those classes share but is private
+/// so that from outside of this library, there is no type relationship between
+/// those three types.
class _PackageName {
_PackageName(this.name, this.source, this.description);
@@ -117,11 +123,14 @@ class _PackageName {
final String name;
/// The name of the [Source] used to look up this package given its
- /// [description]. If this is a root package, this will be `null`.
+ /// [description].
+ ///
+ /// If this is a root package, this will be `null`.
final String source;
- /// The metadata used by the package's [source] to identify and locate it. It
- /// contains whatever [Source]-specific data it needs to be able to get
+ /// The metadata used by the package's [source] to identify and locate it.
+ ///
+ /// It contains whatever [Source]-specific data it needs to be able to get
/// the package. For example, the description of a git sourced package might
/// by the URL "git://github.com/dart/uilib.git".
final description;
@@ -163,8 +172,9 @@ class PackageRef extends _PackageName {
}
}
-/// A reference to a specific version of a package. A package ID contains
-/// enough information to correctly get the package.
+/// A reference to a specific version of a package.
+///
+/// A package ID contains enough information to correctly get the package.
///
/// Note that it's possible for multiple distinct package IDs to point to
/// different packages that have identical contents. For example, the same
diff --git a/lib/src/progress.dart b/lib/src/progress.dart
index d01e95278880552a710f9a6eb680e1b51b224e55..ad1ceb2582e54647ace864deca5fef59f5c76e93 100644
--- a/lib/src/progress.dart
+++ b/lib/src/progress.dart
@@ -18,8 +18,9 @@ class Progress {
/// The [Stopwatch] used to track how long a progress log has been running.
final _stopwatch = new Stopwatch();
- /// The progress message as it's being incrementally appended. When the
- /// progress is done, a single entry will be added to the log for it.
+ /// The progress message as it's being incrementally appended.
+ ///
+ /// When the progress is done, a single entry will be added to the log for it.
final String _message;
/// Gets the current progress time as a parenthesized, formatted string.
diff --git a/lib/src/pubspec.dart b/lib/src/pubspec.dart
index 8c29253492e1c754900e84665afdd90622c3ac0a..a5e3b5bc809e0f142823bba0dad23fd80b5ec2ca 100644
--- a/lib/src/pubspec.dart
+++ b/lib/src/pubspec.dart
@@ -38,8 +38,9 @@ class Pubspec {
/// is unknown or can't be represented by a Uri.
final Uri _location;
- /// All pubspec fields. This includes the fields from which other properties
- /// are derived.
+ /// All pubspec fields.
+ ///
+ /// This includes the fields from which other properties are derived.
final Map fields;
/// The package's name.
@@ -283,10 +284,10 @@ class Pubspec {
}
}
- /// Parses the pubspec stored at [filePath] whose text is [contents]. If the
- /// pubspec doesn't define version for itself, it defaults to [Version.none].
- /// [filePath] may be `null` if the pubspec is not on the user's local
- /// file system.
+ /// Parses the pubspec stored at [filePath] whose text is [contents].
+ ///
+ /// If the pubspec doesn't define a version for itself, it defaults to
+ /// [Version.none].
factory Pubspec.parse(String contents, SourceRegistry sources,
{String expectedName, Uri location}) {
if (contents.trim() == '') return new Pubspec.empty();
@@ -415,8 +416,8 @@ class Pubspec {
() => new VersionConstraint.parse(yaml));
}
- // Make sure the same package doesn't appear as both a regular and dev
- // dependency.
+ /// Makes sure the same package doesn't appear as both a regular and dev
+ /// dependency.
void _checkDependencyOverlap(List<PackageDep> dependencies,
List<PackageDep> devDependencies) {
var dependencyNames = dependencies.map((dep) => dep.name).toSet();
@@ -456,8 +457,9 @@ class Pubspec {
}
}
-/// The environment-related metadata in the pubspec. Corresponds to the data
-/// under the "environment:" key in the pubspec.
+/// The environment-related metadata in the pubspec.
+///
+/// Corresponds to the data under the "environment:" key in the pubspec.
class PubspecEnvironment {
/// The version constraint specifying which SDK versions this package works
/// with.
diff --git a/lib/src/solver/backtracking_solver.dart b/lib/src/solver/backtracking_solver.dart
index 1944eb0135790b50a5754be5f1553031caaaeff5..d96f1574e834822047737209da20d3131a302552 100644
--- a/lib/src/solver/backtracking_solver.dart
+++ b/lib/src/solver/backtracking_solver.dart
@@ -2,11 +2,13 @@
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.
-/// A back-tracking depth-first solver. Attempts to find the best solution for
-/// a root package's transitive dependency graph, where a "solution" is a set
-/// of concrete package versions. A valid solution will select concrete
-/// versions for every package reached from the root package's dependency graph,
-/// and each of those packages will fit the version constraints placed on it.
+/// A back-tracking depth-first solver.
+///
+/// Attempts to find the best solution for a root package's transitive
+/// dependency graph, where a "solution" is a set of concrete package versions.
+/// A valid solution will select concrete versions for every package reached
+/// from the root package's dependency graph, and each of those packages will
+/// fit the version constraints placed on it.
///
/// The solver builds up a solution incrementally by traversing the dependency
/// graph starting at the root package. When it reaches a new package, it gets
@@ -50,9 +52,11 @@ import 'dependency_queue.dart';
import 'version_queue.dart';
import 'version_solver.dart';
-/// The top-level solver. Keeps track of the current potential solution, and
-/// the other possible versions for speculative package selections. Backtracks
-/// and advances to the next potential solution in the case of a failure.
+/// The top-level solver.
+///
+/// Keeps track of the current potential solution, and the other possible
+/// versions for speculative package selections. Backtracks and advances to the
+/// next potential solution in the case of a failure.
class BacktrackingSolver {
final SourceRegistry sources;
final Package root;
@@ -62,8 +66,10 @@ class BacktrackingSolver {
final PubspecCache cache;
- /// The set of packages that are being explicitly upgraded. The solver will
- /// only allow the very latest version for each of these packages.
+ /// The set of packages that are being explicitly upgraded.
+ ///
+ /// The solver will only allow the very latest version for each of these
+ /// packages.
final _forceLatest = new Set<String>();
/// If this is set, the contents of [lockFile] are ignored while solving.
@@ -76,6 +82,9 @@ class BacktrackingSolver {
/// to use the one here.
final _overrides = new Map<String, PackageDep>();
+ /// The package versions currently selected by the solver, along with the
+ /// versions which are remaining to be tried.
+ ///
/// Every time a package is encountered when traversing the dependency graph,
/// the solver must select a version for it, sometimes when multiple versions
/// are valid. This keeps track of which versions have been selected so far
@@ -113,8 +122,10 @@ class BacktrackingSolver {
}
}
- /// Run the solver. Completes with a list of specific package versions if
- /// successful or an error if it failed to find a solution.
+ /// Run the solver.
+ ///
+ /// Completes with a list of specific package versions if successful or an
+ /// error if it failed to find a solution.
Future<SolveResult> solve() {
var stopwatch = new Stopwatch();
@@ -177,10 +188,11 @@ class BacktrackingSolver {
}
/// Adds [versions], which is the list of all allowed versions of a given
- /// package, to the set of versions to consider for solutions. The first item
- /// in the list will be the currently selected version of that package.
- /// Subsequent items will be tried if it the current selection fails. Returns
- /// the first selected version.
+ /// package, to the set of versions to consider for solutions.
+ ///
+ /// The first item in the list will be the currently selected version of that
+ /// package. Subsequent items will be tried if it the current selection fails.
+ /// Returns the first selected version.
PackageId select(VersionQueue versions) {
_selected.add(versions);
logSolve();
@@ -201,8 +213,9 @@ class BacktrackingSolver {
return null;
}
- /// Gets the version of [package] currently locked in the lock file. Returns
- /// `null` if it isn't in the lockfile (or has been unlocked).
+ /// Gets the version of [package] currently locked in the lock file.
+ ///
+ /// Returns `null` if it isn't in the lockfile (or has been unlocked).
PackageId getLocked(String package) {
if (_upgradeAll) return null;
if (_forceLatest.contains(package)) return null;
@@ -211,10 +224,12 @@ class BacktrackingSolver {
}
/// Traverses the root package's dependency graph using the current potential
- /// solution. If successful, completes to the solution. If not, backtracks
- /// to the most recently selected version of a package and tries the next
- /// version of it. If there are no more versions, continues to backtrack to
- /// previous selections, and so on. If there is nothing left to backtrack to,
+ /// solution.
+ ///
+ /// If successful, completes to the solution. If not, backtracks to the most
+ /// recently selected version of a package and tries the next version of it.
+ /// If there are no more versions, continues to backtrack to previous
+ /// selections, and so on. If there is nothing left to backtrack to,
/// completes to the last failure that occurred.
Future<List<PackageId>> _traverseSolution() => resetStack(() {
return new Traverser(this).traverse().catchError((error) {
@@ -233,9 +248,11 @@ class BacktrackingSolver {
});
/// Backtracks from the current failed solution and determines the next
- /// solution to try. If possible, it will backjump based on the cause of the
- /// [failure] to minize backtracking. Otherwise, it will simply backtrack to
- /// the next possible solution.
+ /// solution to try.
+ ///
+ /// If possible, it will backjump based on the cause of the [failure] to
+ /// minize backtracking. Otherwise, it will simply backtrack to the next
+ /// possible solution.
///
/// Returns `true` if there is a new solution to try.
Future<bool> _backtrack(SolveFailure failure) {
@@ -278,9 +295,10 @@ class BacktrackingSolver {
}
/// Walks the selected packages from most to least recent to determine which
- /// ones can be ignored and jumped over by the backtracker. The only packages
- /// we need to backtrack to are ones that led (possibly indirectly) to the
- /// failure. Everything else can be skipped.
+ /// ones can be ignored and jumped over by the backtracker.
+ ///
+ /// The only packages we need to backtrack to are ones that led (possibly
+ /// indirectly) to the failure. Everything else can be skipped.
void _backjump(SolveFailure failure) {
for (var i = _selected.length - 1; i >= 0; i--) {
// Each queue will never be empty since it gets discarded by _backtrack()
@@ -382,8 +400,9 @@ class BacktrackingSolver {
log.solver(buffer.toString().trim());
}
- /// Logs [message] in the context of the current selected packages. If
- /// [message] is omitted, just logs a description of leaf-most selection.
+ /// Logs [message] in the context of the current selected packages.
+ ///
+ /// If [message] is omitted, just logs a description of leaf-most selection.
void logSolve([String message]) {
if (message == null) {
if (_selected.isEmpty) {
@@ -404,26 +423,32 @@ class BacktrackingSolver {
/// Given the solver's current set of selected package versions, this tries to
/// traverse the dependency graph and see if a complete set of valid versions
-/// has been chosen. If it reaches a conflict, it will fail and stop
-/// traversing. If it reaches a package that isn't selected it will refine the
-/// solution by adding that package's set of allowed versions to the solver and
-/// then select the best one and continue.
+/// has been chosen.
+///
+/// If it reaches a conflict, it fails and stops traversing. If it reaches a
+/// package that isn't selected, it refines the solution by adding that
+/// package's set of allowed versions to the solver and then select the best
+/// one and continuing.
class Traverser {
final BacktrackingSolver _solver;
- /// The queue of packages left to traverse. We do a breadth-first traversal
- /// using an explicit queue just to avoid the code complexity of a recursive
- /// asynchronous traversal.
+ /// The queue of packages left to traverse.
+ ///
+ /// We do a breadth-first traversal using an explicit queue just to avoid the
+ /// code complexity of a recursive asynchronous traversal.
final _packages = new Queue<PackageId>();
- /// The packages we have already traversed. Used to avoid traversing the same
- /// package multiple times, and to build the complete solution results.
+ /// The packages we have already traversed.
+ ///
+ /// Used to avoid traversing the same package multiple times, and to build
+ /// the complete solution results.
final _visited = new Set<PackageId>();
- /// The dependencies visited so far in the traversal. For each package name
- /// (the map key) we track the list of dependencies that other packages have
- /// placed on it so that we can calculate the complete constraint for shared
- /// dependencies.
+ /// The dependencies visited so far in the traversal.
+ ///
+ /// For each package name (the map key) we track the list of dependencies
+ /// that other packages have placed on it so that we can calculate the
+ /// complete constraint for shared dependencies.
final _dependencies = <String, List<Dependency>>{};
Traverser(this._solver);
@@ -436,10 +461,11 @@ class Traverser {
return _traversePackage();
}
- /// Traverses the next package in the queue. Completes to a list of package
- /// IDs if the traversal completed successfully and found a solution.
- /// Completes to an error if the traversal failed. Otherwise, recurses to the
- /// next package in the queue, etc.
+ /// Traverses the next package in the queue.
+ ///
+ /// Completes to a list of package IDs if the traversal completed
+ /// successfully and found a solution. Completes to an error if the traversal
+ /// failed. Otherwise, recurses to the next package in the queue, etc.
Future<List<PackageId>> _traversePackage() {
if (_packages.isEmpty) {
// We traversed the whole graph. If we got here, we successfully found
@@ -603,9 +629,10 @@ class Traverser {
}
/// Ensures that dependency [dep] from [depender] is consistent with the
- /// other dependencies on the same package. Throws a [SolveFailure]
- /// exception if not. Only validates sources and descriptions, not the
- /// version.
+ /// other dependencies on the same package.
+ ///
+ /// Throws a [SolveFailure] exception if not. Only validates sources and
+ /// descriptions, not the version.
void _validateDependency(PackageDep dep, PackageId depender) {
// Make sure the dependencies agree on source and description.
var required = _getRequired(dep.name);
@@ -630,10 +657,11 @@ class Traverser {
}
/// Validates the currently selected package against the new dependency that
- /// [dep] and [constraint] place on it. Returns `null` if there is no
- /// currently selected package, throws a [SolveFailure] if the new reference
- /// it not does not allow the previously selected version, or returns the
- /// selected package if successful.
+ /// [dep] and [constraint] place on it.
+ ///
+ /// Returns `null` if there is no currently selected package, throws a
+ /// [SolveFailure] if the new reference it not does not allow the previously
+ /// selected version, or returns the selected package if successful.
PackageId _validateSelected(PackageDep dep, VersionConstraint constraint) {
var selected = _solver.getSelected(dep.name);
if (selected == null) return null;
@@ -648,17 +676,19 @@ class Traverser {
return selected;
}
- /// Gets the list of dependencies for package [name]. Will create an empty
- /// list if needed.
+ /// Gets the list of dependencies for package [name].
+ ///
+ /// Creates an empty list if needed.
List<Dependency> _getDependencies(String name) {
return _dependencies.putIfAbsent(name, () => <Dependency>[]);
}
- /// Gets a "required" reference to the package [name]. This is the first
- /// non-root dependency on that package. All dependencies on a package must
- /// agree on source and description, except for references to the root
- /// package. This will return a reference to that "canonical" source and
- /// description, or `null` if there is no required reference yet.
+ /// Gets a "required" reference to the package [name].
+ ///
+ /// This is the first non-root dependency on that package. All dependencies
+ /// on a package must agree on source and description, except for references
+ /// to the root package. This will return a reference to that "canonical"
+ /// source and description, or `null` if there is no required reference yet.
///
/// This is required because you may have a circular dependency back onto the
/// root package. That second dependency won't be a root dependency and it's
@@ -682,7 +712,9 @@ class Traverser {
/// Gets the package [name] that's currently contained in the lockfile if it
/// meets [constraint] and has the same source and description as other
- /// references to that package. Returns `null` otherwise.
+ /// references to that package.
+ ///
+ /// Returns `null` otherwise.
PackageId _getValidLocked(String name) {
var package = _solver.getLocked(name);
if (package == null) return null;
@@ -709,7 +741,9 @@ class Traverser {
}
/// Ensures that if [pubspec] has an SDK constraint, then it is compatible
-/// with the current SDK. Throws a [SolveFailure] if not.
+/// with the current SDK.
+///
+/// Throws a [SolveFailure] if not.
void _validateSdkConstraint(Pubspec pubspec) {
if (pubspec.environment.sdkVersion.allows(sdk.version)) return;
diff --git a/lib/src/solver/solve_report.dart b/lib/src/solver/solve_report.dart
index b3a147b6c1194b81a3874354004a171f599877f2..0c51d5ddf5cb6729b10a445a5db708d6494210b9 100644
--- a/lib/src/solver/solve_report.dart
+++ b/lib/src/solver/solve_report.dart
@@ -27,7 +27,9 @@ int show(SourceRegistry sources, Package root, LockFile previousLockFile,
/// Unlike [SolveResult], which is the static data describing a resolution,
/// this class contains the mutable state used while generating the report
-/// itself. It's a report builder.
+/// itself.
+///
+/// It's a report builder.
class _SolveReport {
final SourceRegistry _sources;
final Package _root;
diff --git a/lib/src/solver/version_solver.dart b/lib/src/solver/version_solver.dart
index 0803f81cb9dfa22d2ef1d13a2ba2d7237ff2c18d..99ae3a2ddb8beaac6f15042f3186ac5470d64167 100644
--- a/lib/src/solver/version_solver.dart
+++ b/lib/src/solver/version_solver.dart
@@ -64,9 +64,10 @@ class SolveResult {
final SolveFailure error;
/// The number of solutions that were attempted before either finding a
- /// successful solution or exhausting all options. In other words, one more
- /// than the number of times it had to backtrack because it found an invalid
- /// solution.
+ /// successful solution or exhausting all options.
+ ///
+ /// In other words, one more than the number of times it had to backtrack
+ /// because it found an invalid solution.
final int attemptedSolutions;
final SourceRegistry _sources;
@@ -106,6 +107,7 @@ class SolveResult {
}
/// Maintains a cache of previously-requested data: pubspecs and version lists.
+///
/// Used to avoid requesting the same pubspec from the server repeatedly.
class PubspecCache {
final SourceRegistry _sources;
@@ -277,12 +279,14 @@ class Dependency {
/// Base class for all failures that can occur while trying to resolve versions.
abstract class SolveFailure implements ApplicationException {
- /// The name of the package whose version could not be solved. Will be `null`
- /// if the failure is not specific to one package.
+ /// The name of the package whose version could not be solved.
+ ///
+ /// Will be `null` if the failure is not specific to one package.
final String package;
- /// The known dependencies on [package] at the time of the failure. Will be
- /// an empty collection if the failure is not specific to one package.
+ /// The known dependencies on [package] at the time of the failure.
+ ///
+ /// Will be an empty collection if the failure is not specific to one package.
final Iterable<Dependency> dependencies;
final innerError = null;
@@ -319,8 +323,9 @@ abstract class SolveFailure implements ApplicationException {
return buffer.toString();
}
- /// Describes a dependency's reference in the output message. Override this
- /// to highlight which aspect of [dep] led to the failure.
+ /// Describes a dependency's reference in the output message.
+ ///
+ /// Override this to highlight which aspect of [dep] led to the failure.
String _describeDependency(PackageDep dep) =>
"depends on version ${dep.constraint}";
}
diff --git a/lib/src/source.dart b/lib/src/source.dart
index 3f1d5dbc93aa5b298daa73d88210fc898b4e243d..8cfec0ff8d7bf4caa8aa4bb7660e95cfe02b0670 100644
--- a/lib/src/source.dart
+++ b/lib/src/source.dart
@@ -21,8 +21,10 @@ import 'version.dart';
/// package needs a dependency from a cached source, it is first installed in
/// the [SystemCache] and then acquired from there.
abstract class Source {
- /// The name of the source. Should be lower-case, suitable for use in a
- /// filename, and unique accross all sources.
+ /// The name of the source.
+ ///
+ /// Should be lower-case, suitable for use in a filename, and unique accross
+ /// all sources.
String get name;
/// Whether or not this source is the default source.
@@ -49,7 +51,9 @@ abstract class Source {
}
/// Get the list of all versions that exist for the package described by
- /// [description]. [name] is the expected name of the package.
+ /// [description].
+ ///
+ /// [name] is the expected name of the package.
///
/// Note that this does *not* require the packages to be downloaded locally,
/// which is the point. This is used during version resolution to determine
@@ -64,8 +68,10 @@ abstract class Source {
}
/// Loads the (possibly remote) pubspec for the package version identified by
- /// [id]. This may be called for packages that have not yet been downloaded
- /// during the version resolution process.
+ /// [id].
+ ///
+ /// This may be called for packages that have not yet been downloaded during
+ /// the version resolution process.
///
/// Sources should not override this. Instead, they implement [doDescribe].
Future<Pubspec> describe(PackageId id) {
@@ -79,8 +85,10 @@ abstract class Source {
}
/// Loads the (possibly remote) pubspec for the package version identified by
- /// [id]. This may be called for packages that have not yet been downloaded
- /// during the version resolution process.
+ /// [id].
+ ///
+ /// This may be called for packages that have not yet been downloaded during
+ /// the version resolution process.
///
/// This method is effectively protected: subclasses must implement it, but
/// external code should not call this. Instead, call [describe].
@@ -99,6 +107,9 @@ abstract class Source {
/// installed into the cache yet.
Future<String> getDirectory(PackageId id);
+ /// Gives the source a chance to interpret and validate the description for
+ /// a package coming from this source.
+ ///
/// When a [Pubspec] or [LockFile] is parsed, it reads in the description for
/// each dependency. It is up to the dependency's [Source] to determine how
/// that should be interpreted. This will be called during parsing to validate
@@ -137,10 +148,15 @@ abstract class Source {
}
/// Returns whether or not [description1] describes the same package as
- /// [description2] for this source. This method should be light-weight. It
- /// doesn't need to validate that either package exists.
+ /// [description2] for this source.
+ ///
+ /// This method should be light-weight. It doesn't need to validate that
+ /// either package exists.
bool descriptionsEqual(description1, description2);
+ /// Resolves [id] to a more possibly more precise that will uniquely identify
+ /// a package regardless of when the package is requested.
+ ///
/// For some sources, [PackageId]s can point to different chunks of code at
/// different times. This takes such an [id] and returns a future that
/// completes to a [PackageId] that will uniquely specify a single chunk of
diff --git a/lib/src/source/hosted.dart b/lib/src/source/hosted.dart
index d9d1515a7d2640b9a30de38266dbdf9d12e91fb0..396064eeb81c3c4686e7ca8923f0ae950c2ba89a 100644
--- a/lib/src/source/hosted.dart
+++ b/lib/src/source/hosted.dart
@@ -196,8 +196,9 @@ class HostedSource extends CachedSource {
}
/// When an error occurs trying to read something about [package] from [url],
- /// this tries to translate into a more user friendly error message. Always
- /// throws an error, either the original one or a better one.
+ /// this tries to translate into a more user friendly error message.
+ ///
+ /// Always throws an error, either the original one or a better one.
void _throwFriendlyError(error, StackTrace stackTrace, String package,
String url) {
if (error is PubHttpException &&
@@ -222,8 +223,10 @@ class HostedSource extends CachedSource {
}
/// This is the modified hosted source used when pub get or upgrade are run
-/// with "--offline". This uses the system cache to get the list of available
-/// packages and does no network access.
+/// with "--offline".
+///
+/// This uses the system cache to get the list of available packages and does
+/// no network access.
class OfflineHostedSource extends HostedSource {
/// Gets the list of all versions of [name] that are in the system cache.
Future<List<Version>> getVersions(String name, description) {
@@ -305,8 +308,9 @@ String _directoryToUrl(String url) {
}
/// Parses [description] into its server and package name components, then
-/// converts that to a Uri given [pattern]. Ensures the package name is
-/// properly URL encoded.
+/// converts that to a Uri given [pattern].
+///
+/// Ensures the package name is properly URL encoded.
Uri _makeUrl(description, String pattern(String server, String package)) {
var parsed = _parseDescription(description);
var server = parsed.last;
@@ -315,8 +319,9 @@ Uri _makeUrl(description, String pattern(String server, String package)) {
}
/// Parses [id] into its server, package name, and version components, then
-/// converts that to a Uri given [pattern]. Ensures the package name is
-/// properly URL encoded.
+/// converts that to a Uri given [pattern].
+///
+/// Ensures the package name is properly URL encoded.
Uri _makeVersionUrl(PackageId id,
String pattern(String server, String package, String version)) {
var parsed = _parseDescription(id.description);
diff --git a/lib/src/source/path.dart b/lib/src/source/path.dart
index c6d20cd37c5c27103a9a7ae2c512010d29e35bb6..4a92d770b7485159d8a00b082a32ba8089dcee37 100644
--- a/lib/src/source/path.dart
+++ b/lib/src/source/path.dart
@@ -46,10 +46,11 @@ class PathSource extends Source {
Future<String> getDirectory(PackageId id) =>
newFuture(() => _validatePath(id.name, id.description));
- /// Parses a path dependency. This takes in a path string and returns a map.
- /// The "path" key will be the original path but resolved relative to the
- /// containing path. The "relative" key will be `true` if the original path
- /// was relative.
+ /// Parses a path dependency.
+ ///
+ /// This takes in a path string and returns a map. The "path" key will be the
+ /// original path but resolved relative to the containing path. The
+ /// "relative" key will be `true` if the original path was relative.
///
/// A path coming from a pubspec is a simple string. From a lock file, it's
/// an expanded {"path": ..., "relative": ...} map.
@@ -95,9 +96,10 @@ class PathSource extends Source {
};
}
- /// Serializes path dependency's [description]. For the descriptions where
- /// `relative` attribute is `true`, tries to make `path` relative to the
- /// specified [containingPath].
+ /// Serializes path dependency's [description].
+ ///
+ /// For the descriptions where `relative` attribute is `true`, tries to make
+ /// `path` relative to the specified [containingPath].
dynamic serializeDescription(String containingPath, description) {
if (description["relative"]) {
return {
diff --git a/lib/src/source_registry.dart b/lib/src/source_registry.dart
index 15c4bc12e0d8c7cd6862d85835d00a76533450bc..ffac4f8d7d8ac0bf43ba1b94b1b5ce005e36bbcc 100644
--- a/lib/src/source_registry.dart
+++ b/lib/src/source_registry.dart
@@ -24,8 +24,9 @@ class SourceRegistry extends IterableBase<Source> {
return sources.iterator;
}
- /// Sets the default source. This takes a string, which must be the name of a
- /// registered source.
+ /// Sets the default source.
+ ///
+ /// This takes a string, which must be the name of a registered source.
void setDefault(String name) {
if (!_sources.containsKey(name)) {
throw new StateError('Default source $name is not in the registry');
@@ -34,8 +35,10 @@ class SourceRegistry extends IterableBase<Source> {
_default = _sources[name];
}
- /// Registers a new source. This source may not have the same name as a source
- /// that's already been registered.
+ /// Registers a new source.
+ ///
+ /// This source may not have the same name as a source that's already been
+ /// registered.
void register(Source source) {
if (_sources.containsKey(source.name)) {
throw new StateError('Source registry already has a source named '
diff --git a/lib/src/system_cache.dart b/lib/src/system_cache.dart
index 4c48fbad859612912fca43d9125b477a4f2cbb4d..650861522274b37a151e5b3a53a404d73f272ede 100644
--- a/lib/src/system_cache.dart
+++ b/lib/src/system_cache.dart
@@ -37,8 +37,9 @@ class SystemCache {
/// user's file system.
SystemCache(this.rootDir);
- /// Creates a system cache and registers the standard set of sources. If
- /// [isOffline] is `true`, then the offline hosted source will be used.
+ /// Creates a system cache and registers the standard set of sources.
+ ///
+ /// If [isOffline] is `true`, then the offline hosted source will be used.
/// Defaults to `false`.
factory SystemCache.withSources(String rootDir, {bool isOffline: false}) {
var cache = new SystemCache(rootDir);
@@ -55,8 +56,10 @@ class SystemCache {
return cache;
}
- /// Registers a new source. This source must not have the same name as a
- /// source that's already been registered.
+ /// Registers a new source.
+ ///
+ /// This source must not have the same name as a source that's already been
+ /// registered.
void register(Source source) {
source.bind(this);
sources.register(source);
@@ -73,11 +76,12 @@ class SystemCache {
return source.isInSystemCache(id);
}
- /// Create a new temporary directory within the system cache. The system
- /// cache maintains its own temporary directory that it uses to stage
- /// packages into while downloading. It uses this instead of the OS's system
- /// temp directory to ensure that it's on the same volume as the pub system
- /// cache so that it can move the directory from it.
+ /// Create a new temporary directory within the system cache.
+ ///
+ /// The system cache maintains its own temporary directory that it uses to
+ /// stage packages into while downloading. It uses this instead of the OS's
+ /// system temp directory to ensure that it's on the same volume as the pub
+ /// system cache so that it can move the directory from it.
String createTempDir() {
var temp = ensureDir(tempDir);
return io.createTempDir(temp, 'dir');
diff --git a/lib/src/utils.dart b/lib/src/utils.dart
index 8ebc8fe8ec62ebeda14d1fe25ccbcf7dda6cb9d1..1eb69458c415cdffc164832c2f68e4d2d8b8de10 100644
--- a/lib/src/utils.dart
+++ b/lib/src/utils.dart
@@ -412,6 +412,7 @@ Future<Stream> validateStream(Stream stream) {
// TODO(nweiz): remove this when issue 7964 is fixed.
/// Returns a [Future] that will complete to the first element of [stream].
+///
/// Unlike [Stream.first], this is safe to use with single-subscription streams.
Future streamFirst(Stream stream) {
var completer = new Completer();
@@ -441,8 +442,10 @@ Pair<Stream, StreamSubscription> streamWithSubscription(Stream stream) {
// TODO(nweiz): remove this when issue 7787 is fixed.
/// Creates two single-subscription [Stream]s that each emit all values and
-/// errors from [stream]. This is useful if [stream] is single-subscription but
-/// multiple subscribers are necessary.
+/// errors from [stream].
+///
+/// This is useful if [stream] is single-subscription but multiple subscribers
+/// are necessary.
Pair<Stream, Stream> tee(Stream stream) {
var controller1 = new StreamController(sync: true);
var controller2 = new StreamController(sync: true);
@@ -488,6 +491,7 @@ List<String> splitLines(String text) =>
text.split("\n").map((line) => line.replaceFirst(_trailingCR, "")).toList();
/// Converts a stream of arbitrarily chunked strings into a line-by-line stream.
+///
/// The lines don't include line termination characters. A single trailing
/// newline is ignored.
Stream<String> streamToLines(Stream<String> stream) {
@@ -529,7 +533,8 @@ Future<Iterable> futureWhere(Iterable iter, test(value)) {
// pkg/http.
/// Like [String.split], but only splits on the first occurrence of the pattern.
-/// This will always return an array of two elements or fewer.
+///
+/// This always returns an array of two elements or fewer.
List<String> split1(String toSplit, String pattern) {
if (toSplit.isEmpty) return <String>[];
@@ -581,8 +586,10 @@ Set unionAll(Iterable<Set> sets) =>
sets.fold(new Set(), (union, set) => union.union(set));
// TODO(nweiz): remove this when issue 9068 has been fixed.
-/// Whether [uri1] and [uri2] are equal. This consider HTTP URIs to default to
-/// port 80, and HTTPs URIs to default to port 443.
+/// Whether [uri1] and [uri2] are equal.
+///
+/// This consider HTTP URIs to default to port 80, and HTTPs URIs to default to
+/// port 443.
bool urisEqual(Uri uri1, Uri uri2) =>
canonicalizeUri(uri1) == canonicalizeUri(uri2);
@@ -614,14 +621,17 @@ String niceDuration(Duration duration) {
return result + "$s.${ms}s";
}
-/// Decodes a URL-encoded string. Unlike [Uri.decodeComponent], this includes
-/// replacing `+` with ` `.
+/// Decodes a URL-encoded string.
+///
+/// Unlike [Uri.decodeComponent], this includes replacing `+` with ` `.
String urlDecode(String encoded) =>
Uri.decodeComponent(encoded.replaceAll("+", " "));
/// Takes a simple data structure (composed of [Map]s, [Iterable]s, scalar
/// objects, and [Future]s) and recursively resolves all the [Future]s contained
-/// within. Completes with the fully resolved structure.
+/// within.
+///
+/// Completes with the fully resolved structure.
Future awaitObject(object) {
// Unroll nested futures.
if (object is Future) return object.then(awaitObject);
@@ -668,8 +678,9 @@ String getSpecial(String color, [String onWindows = '']) {
}
}
-/// Prepends each line in [text] with [prefix]. If [firstPrefix] is passed, the
-/// first line is prefixed with that instead.
+/// Prepends each line in [text] with [prefix].
+///
+/// If [firstPrefix] is passed, the first line is prefixed with that instead.
String prefixLines(String text, {String prefix: '| ', String firstPrefix}) {
var lines = text.split('\n');
if (firstPrefix == null) {
@@ -711,9 +722,10 @@ Future resetStack(fn()) {
return completer.future;
}
-/// The subset of strings that don't need quoting in YAML. This pattern does
-/// not strictly follow the plain scalar grammar of YAML, which means some
-/// strings may be unnecessarily quoted, but it's much simpler.
+/// The subset of strings that don't need quoting in YAML.
+///
+/// This pattern does not strictly follow the plain scalar grammar of YAML,
+/// which means some strings may be unnecessarily quoted, but it's much simpler.
final _unquotableYamlString = new RegExp(r"^[a-zA-Z_-][a-zA-Z_0-9-]*$");
/// Converts [data], which is a parsed YAML object, to a pretty-printed string,
@@ -774,6 +786,7 @@ String yamlToString(data) {
}
/// An exception class for exceptions that are intended to be seen by the user.
+///
/// These exceptions won't have any debugging information printed when they're
/// thrown.
class ApplicationException implements Exception {
@@ -842,8 +855,9 @@ final _userFacingExceptions = new Set<String>.from([
'WebSocketException'
]);
-/// Returns whether [error] is a user-facing error object. This includes both
-/// [ApplicationException] and any dart:io errors.
+/// Returns whether [error] is a user-facing error object.
+///
+/// This includes both [ApplicationException] and any dart:io errors.
bool isUserFacingException(error) {
if (error is CrossIsolateException) {
return _userFacingExceptions.contains(error.type);
diff --git a/lib/src/validator.dart b/lib/src/validator.dart
index e4480581022eec14d98cd3f288c3c7e6c29d54dd..32194fec7ee0a98536167a83517eeba5d9240092 100644
--- a/lib/src/validator.dart
+++ b/lib/src/validator.dart
@@ -20,18 +20,24 @@ import 'validator/size.dart';
import 'validator/utf8_readme.dart';
/// The base class for validators that check whether a package is fit for
-/// uploading. Each validator should override [errors], [warnings], or both to
-/// return lists of errors or warnings to display to the user. Errors will cause
-/// the package not to be uploaded; warnings will require the user to confirm
-/// the upload.
+/// uploading.
+///
+/// Each validator should override [errors], [warnings], or both to return
+/// lists of errors or warnings to display to the user. Errors will cause the
+/// package not to be uploaded; warnings will require the user to confirm the
+/// upload.
abstract class Validator {
/// The entrypoint that's being validated.
final Entrypoint entrypoint;
- /// The accumulated errors for this validator. Filled by calling [validate].
+ /// The accumulated errors for this validator.
+ ///
+ /// Filled by calling [validate].
final errors = <String>[];
- /// The accumulated warnings for this validator. Filled by calling [validate].
+ /// The accumulated warnings for this validator.
+ ///
+ /// Filled by calling [validate].
final warnings = <String>[];
Validator(this.entrypoint);
@@ -41,8 +47,8 @@ abstract class Validator {
Future validate();
/// Run all validators on the [entrypoint] package and print their results.
- /// The future will complete with the error and warning messages,
- /// respectively.
+ ///
+ /// The future completes with the error and warning messages, respectively.
///
/// [packageSize], if passed, should complete to the size of the tarred
/// package, in bytes. This is used to validate that it's not too big to
diff --git a/lib/src/validator/dependency.dart b/lib/src/validator/dependency.dart
index 0f06d3f637a8a36bacddc3b63ed5fac67cdd6bd0..c341e33cd38b8c3ed36d6c1b18fa7b1727513127 100644
--- a/lib/src/validator/dependency.dart
+++ b/lib/src/validator/dependency.dart
@@ -90,7 +90,7 @@ class DependencyValidator extends Validator {
'future versions of "${dep.name}".');
}
- // Warn that dependencies should allow more than a single version.
+ /// Warn that dependencies should allow more than a single version.
void _warnAboutSingleVersionConstraint(PackageDep dep) {
warnings.add(
'Your dependency on "${dep.name}" should allow more than one version. '
@@ -104,7 +104,7 @@ class DependencyValidator extends Validator {
'along with other packages that also depend on "${dep.name}".');
}
- // Warn that dependencies should have lower bounds on their constraints.
+ /// Warn that dependencies should have lower bounds on their constraints.
void _warnAboutNoConstraintLowerBound(PackageDep dep) {
var message = 'Your dependency on "${dep.name}" should have a lower bound.';
var locked = entrypoint.loadLockFile().packages[dep.name];
@@ -126,7 +126,7 @@ class DependencyValidator extends Validator {
'previous versions of "${dep.name}".');
}
- // Warn that dependencies should have upper bounds on their constraints.
+ /// Warn that dependencies should have upper bounds on their constraints.
void _warnAboutNoConstraintUpperBound(PackageDep dep) {
warnings.add(
'Your dependency on "${dep.name}" should have an upper bound. For '
diff --git a/lib/src/version.dart b/lib/src/version.dart
index a726fd076439ece7427527c7368ebf8473aa8aa0..7e33fe2de8e0909e22e88bcdf70c7ad9b4444888 100644
--- a/lib/src/version.dart
+++ b/lib/src/version.dart
@@ -125,9 +125,10 @@ class Version implements Comparable<Version>, VersionConstraint {
}
}
- /// Returns the primary version out of a list of candidates. This is the
- /// highest-numbered stable (non-prerelease) version. If there are no stable
- /// versions, it's just the highest-numbered version.
+ /// Returns the primary version out of a list of candidates.
+ ///
+ /// This is the highest-numbered stable (non-prerelease) version. If there
+ /// are no stable versions, it's just the highest-numbered version.
static Version primary(List<Version> versions) {
var primary;
for (var version in versions) {
@@ -203,7 +204,7 @@ class Version implements Comparable<Version>, VersionConstraint {
}
/// Gets the next patch version number that follows this one.
- ///bed8b33fda6ec81c3ba52274d189bc0661ed12bf
+ ///
/// If this version is a pre-release, then it just strips the pre-release
/// suffix. Otherwise, it increments the patch version.
Version get nextPatch {
@@ -292,9 +293,11 @@ class Version implements Comparable<Version>, VersionConstraint {
}
/// A [VersionConstraint] is a predicate that can determine whether a given
-/// version is valid or not. For example, a ">= 2.0.0" constraint allows any
-/// version that is "2.0.0" or greater. Version objects themselves implement
-/// this to match a specific version.
+/// version is valid or not.
+///
+/// For example, a ">= 2.0.0" constraint allows any version that is "2.0.0" or
+/// greater. Version objects themselves implement this to match a specific
+/// version.
abstract class VersionConstraint {
/// A [VersionConstraint] that allows all versions.
static VersionConstraint any = new VersionRange();
@@ -302,8 +305,10 @@ abstract class VersionConstraint {
/// A [VersionConstraint] that allows no versions: i.e. the empty set.
static VersionConstraint empty = const _EmptyVersion();
- /// Parses a version constraint. This string is either "any" or a series of
- /// version parts. Each part can be one of:
+ /// Parses a version constraint.
+ ///
+ /// This string is either "any" or a series of version parts. Each part can
+ /// be one of:
///
/// * A version string like `1.2.3`. In other words, anything that can be
/// parsed by [Version.parse()].
@@ -395,9 +400,11 @@ abstract class VersionConstraint {
}
/// Creates a new version constraint that is the intersection of
- /// [constraints]. It will only allow versions that all of those constraints
- /// allow. If constraints is empty, then it returns a VersionConstraint that
- /// allows all versions.
+ /// [constraints].
+ ///
+ /// It only allows versions that all of those constraints allow. If
+ /// constraints is empty, then it returns a VersionConstraint that allows
+ /// all versions.
factory VersionConstraint.intersection(
Iterable<VersionConstraint> constraints) {
var constraint = new VersionRange();
@@ -421,10 +428,11 @@ abstract class VersionConstraint {
VersionConstraint intersect(VersionConstraint other);
}
-/// Constrains versions to a fall within a given range. If there is a minimum,
-/// then this only allows versions that are at that minimum or greater. If there
-/// is a maximum, then only versions less than that are allowed. In other words,
-/// this allows `>= min, < max`.
+/// Constrains versions to a fall within a given range.
+///
+/// If there is a minimum, then this only allows versions that are at that
+/// minimum or greater. If there is a maximum, then only versions less than
+/// that are allowed. In other words, this allows `>= min, < max`.
class VersionRange implements VersionConstraint {
final Version min;
final Version max;
diff --git a/test/test_pub.dart b/test/test_pub.dart
index b89a02729bff21948b283aaacc6120d183d7d8a6..7f82be65a73fa8601b613d67a2008f206eb4abb8 100644
--- a/test/test_pub.dart
+++ b/test/test_pub.dart
@@ -2,10 +2,11 @@
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.
-/// Test infrastructure for testing pub. Unlike typical unit tests, most pub
-/// tests are integration tests that stage some stuff on the file system, run
-/// pub, and then validate the results. This library provides an API to build
-/// tests like that.
+/// Test infrastructure for testing pub.
+///
+/// Unlike typical unit tests, most pub tests are integration tests that stage
+/// some stuff on the file system, run pub, and then validate the results. This
+/// library provides an API to build tests like that.
library test_pub;
import 'dart:async';
@@ -149,10 +150,10 @@ Future<List<String>> getRequestedPaths() {
}, "get previous network requests");
}
-/// Creates an HTTP server to serve [contents] as static files. This server will
-/// exist only for the duration of the pub run.
+/// Creates an HTTP server to serve [contents] as static files.
///
-/// Subsequent calls to [serve] will replace the previous server.
+/// This server will exist only for the duration of the pub run. Subsequent
+/// calls to [serve] replace the previous server.
void serve([List<d.Descriptor> contents]) {
var baseDir = d.dir("serve-dir", contents);
@@ -179,8 +180,9 @@ void serve([List<d.Descriptor> contents]) {
}, 'starting a server serving:\n${baseDir.describe()}');
}
-/// Closes [_server]. Returns a [Future] that will complete after the [_server]
-/// is closed.
+/// Closes [_server].
+///
+/// Returns a [Future] that completes after the [_server] is closed.
Future _closeServer() {
if (_server == null) return new Future.value();
var future = _server.close();
@@ -209,12 +211,14 @@ d.DirectoryDescriptor _servedApiPackageDir;
/// this test.
d.DirectoryDescriptor _servedPackageDir;
-/// A map from package names to parsed pubspec maps for those packages. This
-/// represents the packages currently being served by [servePackages], and is
-/// `null` if [servePackages] has not yet been called for this test.
+/// A map from package names to parsed pubspec maps for those packages.
+///
+/// This represents the packages currently being served by [servePackages], and
+/// is `null` if [servePackages] has not yet been called for this test.
Map<String, List<Map>> _servedPackages;
/// Creates an HTTP server that replicates the structure of pub.dartlang.org.
+///
/// [pubspecs] is a list of unserialized pubspecs representing the packages to
/// serve.
///
@@ -292,15 +296,15 @@ final String pkgPath = path.absolute(path.join(
path.dirname(Platform.executable),
'..', '..', '..', '..', 'pkg'));
-/// The path of the package cache directory used for tests. Relative to the
+/// The path of the package cache directory used for tests, relative to the
/// sandbox directory.
final String cachePath = "cache";
-/// The path of the mock app directory used for tests. Relative to the sandbox
+/// The path of the mock app directory used for tests, relative to the sandbox
/// directory.
final String appPath = "myapp";
-/// The path of the packages directory in the mock app used for tests. Relative
+/// The path of the packages directory in the mock app used for tests, relative
/// to the sandbox directory.
final String packagesPath = "$appPath/packages";
@@ -319,6 +323,8 @@ class RunCommand {
RunCommand(this.name, this.success);
}
+/// Runs the tests defined within [callback] using both pub get and pub upgrade.
+///
/// Many tests validate behavior that is the same between pub get and
/// upgrade have the same behavior. Instead of duplicating those tests, this
/// takes a callback that defines get/upgrade agnostic tests and runs them
@@ -368,8 +374,10 @@ void pubUpgrade({Iterable<String> args, output, error, warning}) {
warning: warning);
}
-/// Defines an integration test. The [body] should schedule a series of
-/// operations which will be run asynchronously.
+/// Defines an integration test.
+///
+/// The [body] should schedule a series of operations which will be run
+/// asynchronously.
void integration(String description, void body()) =>
_integration(description, body, test);
@@ -480,6 +488,7 @@ ScheduledProcess startPublish(ScheduledServer server, {List args}) {
}
/// Handles the beginning confirmation process for uploading a packages.
+///
/// Ensures that the right output is shown and then enters "y" to confirm the
/// upload.
void confirmPublish(ScheduledProcess pub) {
@@ -658,7 +667,7 @@ void ensureGit() {
}
}
-/// Create a lock file for [package] without running `pub get`.
+/// Creates a lock file for [package] without running `pub get`.
///
/// [sandbox] is a list of path dependencies to be found in the sandbox
/// directory. [pkg] is a list of packages in the Dart repo's "pkg" directory;
@@ -728,7 +737,7 @@ void createLockFile(String package, {Iterable<String> sandbox,
lockFile.serialize(null, sources)).create();
}
-/// Use [client] as the mock HTTP client for this test.
+/// Uses [client] as the mock HTTP client for this test.
///
/// Note that this will only affect HTTP requests made via http.dart in the
/// parent process.
@@ -876,8 +885,10 @@ void _validateOutputJson(List<String> failures, String pipe,
/// A function that creates a [Validator] subclass.
typedef Validator ValidatorCreator(Entrypoint entrypoint);
-/// Schedules a single [Validator] to run on the [appPath]. Returns a scheduled
-/// Future that contains the errors and warnings produced by that validator.
+/// Schedules a single [Validator] to run on the [appPath].
+///
+/// Returns a scheduled Future that contains the errors and warnings produced
+/// by that validator.
Future<Pair<List<String>, List<String>>> schedulePackageValidation(
ValidatorCreator fn) {
return schedule(() {