Convert pub tests to line doc comments.

utils/tests/pub/test_pub.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // 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:io';
 import 'dart:isolate';
 import 'dart:json';
 import 'dart:math';
 import 'dart:uri';
 
 import '../../../pkg/oauth2/lib/oauth2.dart' as oauth2;
 import '../../../pkg/path/lib/path.dart' as path;
 import '../../../pkg/unittest/lib/unittest.dart';
 import '../../../pkg/http/lib/testing.dart';
 import '../../lib/file_system.dart' as fs;
 import '../../pub/entrypoint.dart';
 import '../../pub/git_source.dart';
 import '../../pub/hosted_source.dart';
 import '../../pub/http.dart';
 import '../../pub/io.dart';
 import '../../pub/sdk_source.dart';
 import '../../pub/system_cache.dart';
 import '../../pub/utils.dart';
 import '../../pub/validator.dart';
 import '../../pub/yaml/yaml.dart';
 
-/**
- * Creates a new [FileDescriptor] with [name] and [contents].
- */
+/// Creates a new [FileDescriptor] with [name] and [contents].
 FileDescriptor file(Pattern name, String contents) =>
     new FileDescriptor(name, contents);
 
-/**
- * Creates a new [DirectoryDescriptor] with [name] and [contents].
- */
+/// Creates a new [DirectoryDescriptor] with [name] and [contents].
 DirectoryDescriptor dir(Pattern name, [List<Descriptor> contents]) =>
     new DirectoryDescriptor(name, contents);
 
-/**
- * Creates a new [FutureDescriptor] wrapping [future].
- */
+/// Creates a new [FutureDescriptor] wrapping [future].
 FutureDescriptor async(Future<Descriptor> future) =>
     new FutureDescriptor(future);
 
-/**
- * Creates a new [GitRepoDescriptor] with [name] and [contents].
- */
+/// Creates a new [GitRepoDescriptor] with [name] and [contents].
 GitRepoDescriptor git(Pattern name, [List<Descriptor> contents]) =>
     new GitRepoDescriptor(name, contents);
 
-/**
- * Creates a new [TarFileDescriptor] with [name] and [contents].
- */
+/// Creates a new [TarFileDescriptor] with [name] and [contents].
 TarFileDescriptor tar(Pattern name, [List<Descriptor> contents]) =>
     new TarFileDescriptor(name, contents);
 
-/**
- * Creates a new [NothingDescriptor] with [name].
- */
+/// Creates a new [NothingDescriptor] with [name].
 NothingDescriptor nothing(String name) => new NothingDescriptor(name);
 
-/**
- * The current [HttpServer] created using [serve].
- */
+/// The current [HttpServer] created using [serve].
 var _server;
 
-/** The cached value for [_portCompleter]. */
+/// The cached value for [_portCompleter].
 Completer<int> _portCompleterCache;
 
-/** The completer for [port]. */
+/// The completer for [port].
 Completer<int> get _portCompleter {
   if (_portCompleterCache != null) return _portCompleterCache;
   _portCompleterCache = new Completer<int>();
   _scheduleCleanup((_) {
     _portCompleterCache = null;
   });
   return _portCompleterCache;
 }
 
-/**
- * A future that will complete to the port used for the current server.
- */
+/// A future that will complete to the port used for the current server.
 Future<int> get port => _portCompleter.future;
 
-/**
- * Creates an HTTP server to serve [contents] as static files. This server will
- * exist only for the duration of the pub run.
- *
- * Subsequent calls to [serve] will replace the previous server.
- */
+/// Creates an HTTP server to serve [contents] as static files. This server will
+/// exist only for the duration of the pub run.
+///
+/// Subsequent calls to [serve] will replace the previous server.
 void serve([List<Descriptor> contents]) {
   var baseDir = dir("serve-dir", contents);
 
   _schedule((_) {
     return _closeServer().transform((_) {
       _server = new HttpServer();
       _server.defaultRequestHandler = (request, response) {
         var path = request.uri.replaceFirst("/", "").split("/");
         response.persistentConnection = false;
         var stream;
@@ skipping 22 matching lines @@
         });
       };
       _server.listen("127.0.0.1", 0);
       _portCompleter.complete(_server.port);
       _scheduleCleanup((_) => _closeServer());
       return null;
     });
   });
 }
 
-/**
- * Closes [_server]. Returns a [Future] that will complete after the [_server]
- * is closed.
- */
+/// Closes [_server]. Returns a [Future] that will complete after the [_server]
+/// is closed.
 Future _closeServer() {
   if (_server == null) return new Future.immediate(null);
   _server.close();
   _server = null;
   _portCompleterCache = null;
   // TODO(nweiz): Remove this once issue 4155 is fixed. Pumping the event loop
   // *seems* to be enough to ensure that the server is actually closed, but I'm
   // putting this at 10ms to be safe.
   return sleep(10);
 }
 
-/**
- * The [DirectoryDescriptor] describing the server layout of packages that are
- * being served via [servePackages]. This is `null` if [servePackages] has not
- * yet been called for this test.
- */
+/// The [DirectoryDescriptor] describing the server layout of packages that are
+/// being served via [servePackages]. This is `null` if [servePackages] has not
+/// yet been called for this test.
 DirectoryDescriptor _servedPackageDir;
 
-/**
- * A map from package names to version numbers to YAML-serialized pubspecs 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 version numbers to YAML-serialized pubspecs 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, Map<String, String>> _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.
- *
- * Subsequent calls to [servePackages] will add to the set of packages that are
- * being served. Previous packages will continue to be served.
- */
+/// Creates an HTTP server that replicates the structure of pub.dartlang.org.
+/// [pubspecs] is a list of unserialized pubspecs representing the packages to
+/// serve.
+///
+/// Subsequent calls to [servePackages] will add to the set of packages that
+/// are being served. Previous packages will continue to be served.
 void servePackages(List<Map> pubspecs) {
   if (_servedPackages == null || _servedPackageDir == null) {
     _servedPackages = <String, Map<String, String>>{};
     _servedPackageDir = dir('packages', []);
     serve([_servedPackageDir]);
 
     _scheduleCleanup((_) {
       _servedPackages = null;
       _servedPackageDir = null;
     });
@@ skipping 25 matching lines @@
                 ])
               ];
             })))
           ])
         ]);
       }
     });
   });
 }
 
-/** Converts [value] into a YAML string. */
+/// Converts [value] into a YAML string.
 String yaml(value) => JSON.stringify(value);
 
 /// Describes a package that passes all validation.
 Descriptor get normalPackage => dir(appPath, [
   libPubspec("test_pkg", "1.0.0"),
   file("LICENSE", "Eh, do what you want."),
   dir("lib", [
     file("test_pkg.dart", "int i = 1;")
   ])
 ]);
 
-/**
- * Describes a file named `pubspec.yaml` with the given YAML-serialized
- * [contents], which should be a serializable object.
- *
- * [contents] may contain [Future]s that resolve to serializable objects, which
- * may in turn contain [Future]s recursively.
- */
+/// Describes a file named `pubspec.yaml` with the given YAML-serialized
+/// [contents], which should be a serializable object.
+///
+/// [contents] may contain [Future]s that resolve to serializable objects,
+/// which may in turn contain [Future]s recursively.
 Descriptor pubspec(Map contents) {
   return async(_awaitObject(contents).transform((resolvedContents) =>
       file("pubspec.yaml", yaml(resolvedContents))));
 }
 
-/**
- * Describes a file named `pubspec.yaml` for an application package with the
- * given [dependencies].
- */
+/// Describes a file named `pubspec.yaml` for an application package with the
+/// given [dependencies].
 Descriptor appPubspec(List dependencies) {
   return pubspec({
     "name": "myapp",
     "dependencies": _dependencyListToMap(dependencies)
   });
 }
 
-/**
- * Describes a file named `pubspec.yaml` for a library package with the given
- * [name], [version], and [dependencies].
- */
+/// Describes a file named `pubspec.yaml` for a library package with the given
+/// [name], [version], and [dependencies].
 Descriptor libPubspec(String name, String version, [List dependencies]) =>
   pubspec(package(name, version, dependencies));
 
-/**
- * Describes a directory named `lib` containing a single dart file named
- * `<name>.dart` that contains a line of Dart code.
- */
+/// Describes a directory named `lib` containing a single dart file named
+/// `<name>.dart` that contains a line of Dart code.
 Descriptor libDir(String name, [String code]) {
   // Default to printing the name if no other code was given.
   if (code == null) {
     code = name;
   }
 
   return dir("lib", [
     file("$name.dart", 'main() => "$code";')
   ]);
 }
 
-/**
- * Describes a map representing a library package with the given [name],
- * [version], and [dependencies].
- */
+/// Describes a map representing a library package with the given [name],
+/// [version], and [dependencies].
 Map package(String name, String version, [List dependencies]) {
   var package = {
     "name": name,
     "version": version,
     "author": "Nathan Weizenbaum <nweiz@google.com>",
     "homepage": "http://pub.dartlang.org",
     "description": "A package, I guess."
   };
   if (dependencies != null) {
     package["dependencies"] = _dependencyListToMap(dependencies);
   }
   return package;
 }
 
-/**
- * Describes a map representing a dependency on a package in the package
- * repository.
- */
+/// Describes a map representing a dependency on a package in the package
+/// repository.
 Map dependency(String name, [String versionConstraint]) {
   var url = port.transform((p) => "http://localhost:$p");
   var dependency = {"hosted": {"name": name, "url": url}};
   if (versionConstraint != null) dependency["version"] = versionConstraint;
   return dependency;
 }
 
-/**
- * Describes a directory for a package installed from the mock package server.
- * This directory is of the form found in the global package cache.
- */
+/// Describes a directory for a package installed from the mock package server.
+/// This directory is of the form found in the global package cache.
 DirectoryDescriptor packageCacheDir(String name, String version) {
   return dir("$name-$version", [
     libDir(name, '$name $version')
   ]);
 }
 
-/**
- * Describes a directory for a Git package. This directory is of the form found
- * in the revision cache of the global package cache.
- */
+/// Describes a directory for a Git package. This directory is of the form
+/// found in the revision cache of the global package cache.
 DirectoryDescriptor gitPackageRevisionCacheDir(String name, [int modifier]) {
   var value = name;
   if (modifier != null) value = "$name $modifier";
   return dir(new RegExp("$name${r'-[a-f0-9]+'}"), [
     libDir(name, value)
   ]);
 }
 
-/**
- * Describes a directory for a Git package. This directory is of the form found
- * in the repo cache of the global package cache.
- */
+/// Describes a directory for a Git package. This directory is of the form
+/// found in the repo cache of the global package cache.
 DirectoryDescriptor gitPackageRepoCacheDir(String name) {
   return dir(new RegExp("$name${r'-[a-f0-9]+'}"), [
     dir('hooks'),
     dir('info'),
     dir('objects'),
     dir('refs')
   ]);
 }
 
-/**
- * Describes the `packages/` directory containing all the given [packages],
- * which should be name/version pairs. The packages will be validated against
- * the format produced by the mock package server.
- *
- * A package with a null version should not be installed.
- */
+/// Describes the `packages/` directory containing all the given [packages],
+/// which should be name/version pairs. The packages will be validated against
+/// the format produced by the mock package server.
+///
+/// A package with a null version should not be installed.
 DirectoryDescriptor packagesDir(Map<String, String> packages) {
   var contents = <Descriptor>[];
   packages.forEach((name, version) {
     if (version == null) {
       contents.add(nothing(name));
     } else {
       contents.add(dir(name, [
         file("$name.dart", 'main() => "$name $version";')
       ]));
     }
   });
   return dir(packagesPath, contents);
 }
 
-/**
- * Describes the global package cache directory containing all the given
- * [packages], which should be name/version pairs. The packages will be
- * validated against the format produced by the mock package server.
- *
- * A package's value may also be a list of versions, in which case all versions
- * are expected to be installed.
- */
+/// Describes the global package cache directory containing all the given
+/// [packages], which should be name/version pairs. The packages will be
+/// validated against the format produced by the mock package server.
+///
+/// A package's value may also be a list of versions, in which case all
+/// versions are expected to be installed.
 DirectoryDescriptor cacheDir(Map packages) {
   var contents = <Descriptor>[];
   packages.forEach((name, versions) {
     if (versions is! List) versions = [versions];
     for (var version in versions) {
       contents.add(packageCacheDir(name, version));
     }
   });
   return dir(cachePath, [
     dir('hosted', [
@@ skipping 15 matching lines @@
       file('credentials.json', new oauth2.Credentials(
           accessToken,
           refreshToken,
           url.resolve('/token'),
           ['https://www.googleapis.com/auth/userinfo.email'],
           expiration).toJson())
     ]);
   }));
 }
 
-/**
- * Describes the application directory, containing only a pubspec specifying the
- * given [dependencies].
- */
+/// Describes the application directory, containing only a pubspec specifying
+/// the given [dependencies].
 DirectoryDescriptor appDir(List dependencies) =>
   dir(appPath, [appPubspec(dependencies)]);
 
-/**
- * Converts a list of dependencies as passed to [package] into a hash as used in
- * a pubspec.
- */
+/// Converts a list of dependencies as passed to [package] into a hash as used
+/// in a pubspec.
 Future<Map> _dependencyListToMap(List<Map> dependencies) {
   return _awaitObject(dependencies).transform((resolvedDependencies) {
     var result = <String, Map>{};
     for (var dependency in resolvedDependencies) {
       var keys = dependency.keys.filter((key) => key != "version");
       var sourceName = only(keys);
       var source;
       switch (sourceName) {
       case "git":
         source = new GitSource();
@@ skipping 24 matching lines @@
   case "hosted":
     if (description is String) return description;
     return description['name'];
   case "sdk":
     return description;
   default:
     return description;
   }
 }
 
-/**
- * The path of the package cache directory used for tests. Relative to the
- * sandbox directory.
- */
+/// The path of the package cache directory used for tests. Relative to the
+/// sandbox directory.
 final String cachePath = "cache";
 
-/**
- * The path of the mock SDK directory used for tests. Relative to the sandbox
- * directory.
- */
+/// The path of the mock SDK directory used for tests. Relative to the sandbox
+/// directory.
 final String sdkPath = "sdk";
 
-/**
- * The path of the mock app directory used for tests. Relative to the sandbox
- * directory.
- */
+/// 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
- * to the sandbox directory.
- */
+/// The path of the packages directory in the mock app used for tests. Relative
+/// to the sandbox directory.
 final String packagesPath = "$appPath/packages";
 
-/**
- * The type for callbacks that will be fired during [runPub]. Takes the sandbox
- * directory as a parameter.
- */
+/// The type for callbacks that will be fired during [runPub]. Takes the
+/// sandbox directory as a parameter.
 typedef Future _ScheduledEvent(Directory parentDir);
 
-/**
- * The list of events that are scheduled to run as part of the test case.
- */
+/// The list of events that are scheduled to run as part of the test case.
 List<_ScheduledEvent> _scheduled;
 
-/**
- * The list of events that are scheduled to run after the test case, even if it
- * failed.
- */
+/// The list of events that are scheduled to run after the test case, even if
+/// it failed.
 List<_ScheduledEvent> _scheduledCleanup;
 
 /// The list of events that are scheduled to run after the test case only if it
 /// failed.
 List<_ScheduledEvent> _scheduledOnException;
 
-/**
- * Set to true when the current batch of scheduled events should be aborted.
- */
+/// Set to true when the current batch of scheduled events should be aborted.
 bool _abortScheduled = false;
 
 /// The time (in milliseconds) to wait for the entire scheduled test to
 /// complete.
 final _TIMEOUT = 30000;
 
-/**
- * Runs all the scheduled events for a test case. This should only be called
- * once per test case.
- */
+/// Runs all the scheduled events for a test case. This should only be called
+/// once per test case.
 void run() {
   var createdSandboxDir;
 
   var asyncDone = expectAsync0(() {});
 
   Future cleanup() {
     return _runScheduled(createdSandboxDir, _scheduledCleanup).chain((_) {
       _scheduled = null;
       _scheduledCleanup = null;
       _scheduledOnException = null;
@@ skipping 21 matching lines @@
     });
     subFuture.then((_) => registerException(error, future.stackTrace));
     return true;
   });
 
   timeout(future, _TIMEOUT, 'waiting for a test to complete')
       .chain((_) => cleanup())
       .then((_) => asyncDone());
 }
 
-/// Get the path to the root "util/test/pub" directory containing the pub tests.
+/// Get the path to the root "util/test/pub" directory containing the pub
+/// tests.
 String get testDirectory {
   var dir = new Options().script;
   while (basename(dir) != 'pub') dir = dirname(dir);
 
   return getFullPath(dir);
 }
 
-/**
- * Schedules a call to the Pub command-line utility. Runs Pub with [args] and
- * validates that its results match [output], [error], and [exitCode].
- */
+/// Schedules a call to the Pub command-line utility. Runs Pub with [args] and
+/// validates that its results match [output], [error], and [exitCode].
 void schedulePub({List args, Pattern output, Pattern error,
     Future<Uri> tokenEndpoint, int exitCode: 0}) {
   _schedule((sandboxDir) {
     return _doPub(runProcess, sandboxDir, args, tokenEndpoint)
         .transform((result) {
       var failures = [];
 
       _validateOutput(failures, 'stdout', output, result.stdout);
       _validateOutput(failures, 'stderr', error, result.stderr);
 
@@ skipping 102 matching lines @@
 
     if (tokenEndpoint != null) {
       environment['_PUB_TEST_TOKEN_ENDPOINT'] = tokenEndpoint.toString();
     }
 
     return fn(dartBin, dartArgs, workingDir: pathInSandbox(appPath),
         environment: environment);
   });
 }
 
-/**
- * Skips the current test if Git is not installed. This validates that the
- * current test is running on a buildbot in which case we expect git to be
- * installed. If we are not running on the buildbot, we will instead see if git
- * is installed and skip the test if not. This way, users don't need to have git
- * installed to run the tests locally (unless they actually care about the pub
- * git tests).
- */
+/// Skips the current test if Git is not installed. This validates that the
+/// current test is running on a buildbot in which case we expect git to be
+/// installed. If we are not running on the buildbot, we will instead see if
+/// git is installed and skip the test if not. This way, users don't need to
+/// have git installed to run the tests locally (unless they actually care
+/// about the pub git tests).
 void ensureGit() {
   _schedule((_) {
     return isGitInstalled.transform((installed) {
       if (!installed &&
           !Platform.environment.containsKey('BUILDBOT_BUILDERNAME')) {
         _abortScheduled = true;
       }
       return null;
     });
   });
@@ skipping 28 matching lines @@
     if (future != null) {
       return future.chain(runNextEvent);
     } else {
       return runNextEvent(null);
     }
   }
 
   return runNextEvent(null);
 }
 
-/**
- * Compares the [actual] output from running pub with [expected]. For [String]
- * patterns, ignores leading and trailing whitespace differences and tries to
- * report the offending difference in a nice way. For other [Pattern]s, just
- * reports whether the output contained the pattern.
- */
+/// Compares the [actual] output from running pub with [expected]. For [String]
+/// patterns, ignores leading and trailing whitespace differences and tries to
+/// report the offending difference in a nice way. For other [Pattern]s, just
+/// reports whether the output contained the pattern.
 void _validateOutput(List<String> failures, String pipe, Pattern expected,
                      List<String> actual) {
   if (expected == null) return;
 
   if (expected is RegExp) {
     _validateOutputRegex(failures, pipe, expected, actual);
   } else {
     _validateOutputString(failures, pipe, expected, actual);
   }
 }
@@ skipping 51 matching lines @@
 
   // If any lines mismatched, show the expected and actual.
   if (failed) {
     failures.add('Expected $pipe:');
     failures.addAll(expected.map((line) => '| $line'));
     failures.add('Got:');
     failures.addAll(results);
   }
 }
 
-/**
- * Base class for [FileDescriptor] and [DirectoryDescriptor] so that a
- * directory can contain a heterogeneous collection of files and
- * subdirectories.
- */
+/// Base class for [FileDescriptor] and [DirectoryDescriptor] so that a
+/// directory can contain a heterogeneous collection of files and
+/// subdirectories.
 abstract class Descriptor {
-  /**
-   * The name of this file or directory. This must be a [String] if the fiel or
-   * directory is going to be created.
-   */
+  /// The name of this file or directory. This must be a [String] if the file
+  /// or directory is going to be created.
   final Pattern name;
 
   Descriptor(this.name);
 
-  /**
-   * Creates the file or directory within [dir]. Returns a [Future] that is
-   * completed after the creation is done.
-   */
+  /// Creates the file or directory within [dir]. Returns a [Future] that is
+  /// completed after the creation is done.
   Future create(dir);
 
-  /**
-   * Validates that this descriptor correctly matches the corresponding file
-   * system entry within [dir]. Returns a [Future] that completes to `null` if
-   * the entry is valid, or throws an error if it failed.
-   */
+  /// Validates that this descriptor correctly matches the corresponding file
+  /// system entry within [dir]. Returns a [Future] that completes to `null` if
+  /// the entry is valid, or throws an error if it failed.
   Future validate(String dir);
 
-  /**
-   * Deletes the file or directory within [dir]. Returns a [Future] that is
-   * completed after the deletion is done.
-   */
+  /// Deletes the file or directory within [dir]. Returns a [Future] that is
+  /// completed after the deletion is done.
   Future delete(String dir);
 
-  /**
-   * Loads the file at [path] from within this descriptor. If [path] is empty,
-   * loads the contents of the descriptor itself.
-   */
+  /// Loads the file at [path] from within this descriptor. If [path] is empty,
+  /// loads the contents of the descriptor itself.
   InputStream load(List<String> path);
 
-  /**
-   * Schedules the directory to be created before Pub is run with [runPub]. The
-   * directory will be created relative to the sandbox directory.
-   */
+  /// Schedules the directory to be created before Pub is run with [runPub].
+  /// The directory will be created relative to the sandbox directory.
   // TODO(nweiz): Use implicit closurization once issue 2984 is fixed.
   void scheduleCreate() => _schedule((dir) => this.create(dir));
 
-  /**
-   * Schedules the file or directory to be deleted recursively.
-   */
+  /// Schedules the file or directory to be deleted recursively.
   void scheduleDelete() => _schedule((dir) => this.delete(dir));
 
-  /**
-   * Schedules the directory to be validated after Pub is run with [runPub]. The
-   * directory will be validated relative to the sandbox directory.
-   */
+  /// Schedules the directory to be validated after Pub is run with [runPub].
+  /// The directory will be validated relative to the sandbox directory.
   void scheduleValidate() => _schedule((parentDir) => validate(parentDir.path));
 
-  /**
-   * Asserts that the name of the descriptor is a [String] and returns it.
-   */
+  /// Asserts that the name of the descriptor is a [String] and returns it.
   String get _stringName {
     if (name is String) return name;
     throw 'Pattern $name must be a string.';
   }
 
-  /**
-   * Validates that at least one file in [dir] matching [name] is valid
-   * according to [validate]. [validate] should complete to an exception if the
-   * input path is invalid.
-   */
+  /// Validates that at least one file in [dir] matching [name] is valid
+  /// according to [validate]. [validate] should complete to an exception if
+  /// the input path is invalid.
   Future _validateOneMatch(String dir, Future validate(String path)) {
     // Special-case strings to support multi-level names like "myapp/packages".
     if (name is String) {
       var path = join(dir, name);
       return exists(path).chain((exists) {
         if (!exists) Expect.fail('File $name in $dir not found.');
         return validate(path);
       });
     }
 
@@ skipping 43 matching lines @@
         future.then((_) {
           successes++;
           checkComplete();
         });
       }
       return completer.future;
     });
   }
 }
 
-/**
- * Describes a file. These are used both for setting up an expected directory
- * tree before running a test, and for validating that the file system matches
- * some expectations after running it.
- */
+/// Describes a file. These are used both for setting up an expected directory
+/// tree before running a test, and for validating that the file system matches
+/// some expectations after running it.
 class FileDescriptor extends Descriptor {
-  /**
-   * The text contents of the file.
-   */
+  /// The text contents of the file.
   final String contents;
 
   FileDescriptor(Pattern name, this.contents) : super(name);
 
-  /**
-   * Creates the file within [dir]. Returns a [Future] that is completed after
-   * the creation is done.
-   */
+  /// Creates the file within [dir]. Returns a [Future] that is completed after
+  /// the creation is done.
   Future<File> create(dir) {
     return writeTextFile(join(dir, _stringName), contents);
   }
 
-  /**
-   * Deletes the file within [dir]. Returns a [Future] that is completed after
-   * the deletion is done.
-   */
+  /// Deletes the file within [dir]. Returns a [Future] that is completed after
+  /// the deletion is done.
   Future delete(dir) {
     return deleteFile(join(dir, _stringName));
   }
 
-  /**
-   * Validates that this file correctly matches the actual file at [path].
-   */
+  /// Validates that this file correctly matches the actual file at [path].
   Future validate(String path) {
     return _validateOneMatch(path, (file) {
       return readTextFile(file).transform((text) {
         if (text == contents) return null;
 
         Expect.fail('File $file should contain:\n\n$contents\n\n'
                     'but contained:\n\n$text');
       });
     });
   }
 
-  /**
-   * Loads the contents of the file.
-   */
+  /// Loads the contents of the file.
   InputStream load(List<String> path) {
     if (!path.isEmpty) {
       var joinedPath = Strings.join(path, '/');
       throw "Can't load $joinedPath from within $name: not a directory.";
     }
 
     var stream = new ListInputStream();
     stream.write(contents.charCodes);
     stream.markEndOfStream();
     return stream;
   }
 }
 
-/**
- * Describes a directory and its contents. These are used both for setting up
- * an expected directory tree before running a test, and for validating that
- * the file system matches some expectations after running it.
- */
+/// Describes a directory and its contents. These are used both for setting up
+/// an expected directory tree before running a test, and for validating that
+/// the file system matches some expectations after running it.
 class DirectoryDescriptor extends Descriptor {
-  /**
-   * The files and directories contained in this directory.
-   */
+  /// The files and directories contained in this directory.
   final List<Descriptor> contents;
 
   DirectoryDescriptor(Pattern name, List<Descriptor> contents)
     : this.contents = contents == null ? <Descriptor>[] : contents,
       super(name);
 
-  /**
-   * Creates the file within [dir]. Returns a [Future] that is completed after
-   * the creation is done.
-   */
+  /// Creates the file within [dir]. Returns a [Future] that is completed after
+  /// the creation is done.
   Future<Directory> create(parentDir) {
     // Create the directory.
     return ensureDir(join(parentDir, _stringName)).chain((dir) {
       if (contents == null) return new Future<Directory>.immediate(dir);
 
       // Recursively create all of its children.
       final childFutures = contents.map((child) => child.create(dir));
       // Only complete once all of the children have been created too.
       return Futures.wait(childFutures).transform((_) => dir);
     });
   }
 
-  /**
-   * Deletes the directory within [dir]. Returns a [Future] that is completed
-   * after the deletion is done.
-   */
+  /// Deletes the directory within [dir]. Returns a [Future] that is completed
+  /// after the deletion is done.
   Future delete(dir) {
     return deleteDir(join(dir, _stringName));
   }
 
-  /**
-   * Validates that the directory at [path] contains all of the expected
-   * contents in this descriptor. Note that this does *not* check that the
-   * directory doesn't contain other unexpected stuff, just that it *does*
-   * contain the stuff we do expect.
-   */
+  /// Validates that the directory at [path] contains all of the expected
+  /// contents in this descriptor. Note that this does *not* check that the
+  /// directory doesn't contain other unexpected stuff, just that it *does*
+  /// contain the stuff we do expect.
   Future validate(String path) {
     return _validateOneMatch(path, (dir) {
       // Validate each of the items in this directory.
       final entryFutures = contents.map((entry) => entry.validate(dir));
 
       // If they are all valid, the directory is valid.
       return Futures.wait(entryFutures).transform((entries) => null);
     });
   }
 
-  /**
-   * Loads [path] from within this directory.
-   */
+  /// Loads [path] from within this directory.
   InputStream load(List<String> path) {
     if (path.isEmpty) {
       throw "Can't load the contents of $name: is a directory.";
     }
 
     for (var descriptor in contents) {
       if (descriptor.name == path[0]) {
         return descriptor.load(path.getRange(1, path.length - 1));
       }
     }
 
     throw "Directory $name doesn't contain ${Strings.join(path, '/')}.";
   }
 }
 
-/**
- * Wraps a [Future] that will complete to a [Descriptor] and makes it behave
- * like a concrete [Descriptor]. This is necessary when the contents of the
- * descriptor depends on information that's not available until part of the test
- * run is completed.
- */
+/// Wraps a [Future] that will complete to a [Descriptor] and makes it behave
+/// like a concrete [Descriptor]. This is necessary when the contents of the
+/// descriptor depends on information that's not available until part of the
+/// test run is completed.
 class FutureDescriptor extends Descriptor {
   Future<Descriptor> _future;
 
   FutureDescriptor(this._future) : super('<unknown>');
 
   Future create(dir) => _future.chain((desc) => desc.create(dir));
 
   Future validate(dir) => _future.chain((desc) => desc.validate(dir));
 
   Future delete(dir) => _future.chain((desc) => desc.delete(dir));
 
   InputStream load(List<String> path) {
     var resultStream = new ListInputStream();
     _future.then((desc) => pipeInputToInput(desc.load(path), resultStream));
     return resultStream;
   }
 }
 
-/**
- * Describes a Git repository and its contents.
- */
+/// Describes a Git repository and its contents.
 class GitRepoDescriptor extends DirectoryDescriptor {
   GitRepoDescriptor(Pattern name, List<Descriptor> contents)
   : super(name, contents);
 
-  /**
-   * Creates the Git repository and commits the contents.
-   */
+  /// Creates the Git repository and commits the contents.
   Future<Directory> create(parentDir) {
     return _runGitCommands(parentDir, [
       ['init'],
       ['add', '.'],
       ['commit', '-m', 'initial commit']
     ]);
   }
 
-  /**
-   * Commits any changes to the Git repository.
-   */
+  /// Commits any changes to the Git repository.
   Future commit(parentDir) {
     return _runGitCommands(parentDir, [
       ['add', '.'],
       ['commit', '-m', 'update']
     ]);
   }
 
-  /**
-   * Schedules changes to be committed to the Git repository.
-   */
+  /// Schedules changes to be committed to the Git repository.
   void scheduleCommit() => _schedule((dir) => this.commit(dir));
 
-  /**
-   * Return a Future that completes to the commit in the git repository referred
-   * to by [ref] at the current point in the scheduled test run.
-   */
+  /// Return a Future that completes to the commit in the git repository
+  /// referred to by [ref] at the current point in the scheduled test run.
   Future<String> revParse(String ref) {
     return _scheduleValue((parentDir) {
       return super.create(parentDir).chain((rootDir) {
         return _runGit(['rev-parse', ref], rootDir);
       }).transform((output) => output[0]);
     });
   }
 
   /// Schedule a Git command to run in this repository.
   void scheduleGit(List<String> args) {
@@ skipping 33 matching lines @@
       if (!result.success) {
         throw "Error running: git ${Strings.join(args, ' ')}\n"
             "${Strings.join(result.stderr, '\n')}";
       }
 
       return result.stdout;
     });
   }
 }
 
-/**
- * Describes a gzipped tar file and its contents.
- */
+/// Describes a gzipped tar file and its contents.
 class TarFileDescriptor extends Descriptor {
   final List<Descriptor> contents;
 
   TarFileDescriptor(Pattern name, this.contents)
   : super(name);
 
-  /**
-   * Creates the files and directories within this tar file, then archives them,
-   * compresses them, and saves the result to [parentDir].
-   */
+  /// Creates the files and directories within this tar file, then archives
+  /// them, compresses them, and saves the result to [parentDir].
   Future<File> create(parentDir) {
     // TODO(rnystrom): Use withTempDir().
     var tempDir;
     return createTempDir().chain((_tempDir) {
       tempDir = _tempDir;
       return Futures.wait(contents.map((child) => child.create(tempDir)));
     }).chain((createdContents) {
       return consumeInputStream(createTarGz(createdContents, baseDir: tempDir));
     }).chain((bytes) {
       return new File(join(parentDir, _stringName)).writeAsBytes(bytes);
     }).chain((file) {
       return deleteDir(tempDir).transform((_) => file);
     });
   }
 
-  /**
-   * Validates that the `.tar.gz` file at [path] contains the expected contents.
-   */
+  /// Validates that the `.tar.gz` file at [path] contains the expected
+  /// contents.
   Future validate(String path) {
     throw "TODO(nweiz): implement this";
   }
 
   Future delete(dir) {
     throw new UnsupportedError('');
   }
 
-  /**
-   * Loads the contents of this tar file.
-   */
+  /// Loads the contents of this tar file.
   InputStream load(List<String> path) {
     if (!path.isEmpty) {
       var joinedPath = Strings.join(path, '/');
       throw "Can't load $joinedPath from within $name: not a directory.";
     }
 
     var sinkStream = new ListInputStream();
     var tempDir;
     // TODO(rnystrom): Use withTempDir() here.
     // TODO(nweiz): propagate any errors to the return value. See issue 3657.
     createTempDir().chain((_tempDir) {
       tempDir = _tempDir;
       return create(tempDir);
     }).then((tar) {
       var sourceStream = tar.openInputStream();
       pipeInputToInput(sourceStream, sinkStream).then((_) {
         tempDir.delete(recursive: true);
       });
     });
     return sinkStream;
   }
 }
 
-/**
- * A descriptor that validates that no file exists with the given name.
- */
+/// A descriptor that validates that no file exists with the given name.
 class NothingDescriptor extends Descriptor {
   NothingDescriptor(String name) : super(name);
 
   Future create(dir) => new Future.immediate(null);
   Future delete(dir) => new Future.immediate(null);
 
   Future validate(String dir) {
     return exists(join(dir, name)).transform((exists) {
       if (exists) Expect.fail('File $name in $dir should not exist.');
     });
@@ skipping 245 matching lines @@
         return;
       });
     }
 
     return printStream('stdout', _stdout.value)
         .chain((_) => printStream('stderr', _stderr.value));
   }
 }
 
 /// A class representing an [HttpServer] that's scheduled to run in the course
-/// of the test. This class allows the server's request handling to be scheduled
-/// synchronously. All operations on this class are scheduled.
+/// of the test. This class allows the server's request handling to be
+/// scheduled synchronously. All operations on this class are scheduled.
 class ScheduledServer {
   /// The wrapped server.
   final Future<HttpServer> _server;
 
   /// The queue of handlers to run for upcoming requests.
   final _handlers = new Queue<Future>();
 
   /// The requests to be ignored.
   final _ignored = new Set<Pair<String, String>>();
 
@@ skipping 57 matching lines @@
       }
       return _handlers.removeFirst();
     }).transform((handler) {
       handler(request, response);
     }), _SCHEDULE_TIMEOUT, "waiting for a handler for ${request.method} "
         "${request.path}");
     expect(future, completes);
   }
 }
 
-/**
- * Takes a simple data structure (composed of [Map]s, [List]s, scalar objects,
- * and [Future]s) and recursively resolves all the [Future]s contained within.
- * Completes with the fully resolved structure.
- */
+/// Takes a simple data structure (composed of [Map]s, [List]s, scalar objects,
+/// and [Future]s) and recursively resolves all the [Future]s contained within.
+/// Completes with the fully resolved structure.
 Future _awaitObject(object) {
   // Unroll nested futures.
   if (object is Future) return object.chain(_awaitObject);
   if (object is Collection) return Futures.wait(object.map(_awaitObject));
   if (object is! Map) return new Future.immediate(object);
 
   var pairs = <Future<Pair>>[];
   object.forEach((key, value) {
     pairs.add(_awaitObject(value)
         .transform((resolved) => new Pair(key, resolved)));
   });
   return Futures.wait(pairs).transform((resolvedPairs) {
     var map = {};
     for (var pair in resolvedPairs) {
       map[pair.first] = pair.last;
     }
     return map;
   });
 }
 
-/**
- * Schedules a callback to be called as part of the test case.
- */
+/// Schedules a callback to be called as part of the test case.
 void _schedule(_ScheduledEvent event) {
   if (_scheduled == null) _scheduled = [];
   _scheduled.add(event);
 }
 
 /// Like [_schedule], but pipes the return value of [event] to a returned
 /// [Future].
 Future _scheduleValue(_ScheduledEvent event) {
   var completer = new Completer();
   _schedule((parentDir) {
     chainToCompleter(event(parentDir), completer);
     return completer.future;
   });
   return completer.future;
 }
 
-/// Schedules a callback to be called after the test case has completed, even if
-/// it failed.
+/// Schedules a callback to be called after the test case has completed, even
+/// if it failed.
 void _scheduleCleanup(_ScheduledEvent event) {
   if (_scheduledCleanup == null) _scheduledCleanup = [];
   _scheduledCleanup.add(event);
 }
 
 /// Schedules a callback to be called after the test case has completed, but
 /// only if it failed.
 void _scheduleOnException(_ScheduledEvent event) {
   if (_scheduledOnException == null) _scheduledOnException = [];
   _scheduledOnException.add(event);
 }
 
 /// Like [expect], but for [Future]s that complete as part of the scheduled
 /// test. This is necessary to ensure that the exception thrown by the
 /// expectation failing is handled by the scheduler.
 ///
 /// Note that [matcher] matches against the completed value of [actual], so
 /// calling [completion] is unnecessary.
 void expectLater(Future actual, matcher, {String reason,
     FailureHandler failureHandler, bool verbose: false}) {
   _schedule((_) {
     return actual.transform((value) {
       expect(value, matcher, reason: reason, failureHandler: failureHandler,
           verbose: false);
     });
   });
 }