Update doc comments to follow style guide.

sdk/lib/_internal/pub/test/test_pub.dart

 // Copyright (c) 2013, 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:async';
 import 'dart:convert';
 import 'dart:io';
 import 'dart:math';
 
 import 'package:http/testing.dart';
 import 'package:path/path.dart' as path;
 import 'package:scheduled_test/scheduled_process.dart';
@@ skipping 123 matching lines @@
 /// Gets the list of paths that have been requested from the server since the
 /// last time this was called (or since the server was first spun up).
 Future<List<String>> getRequestedPaths() {
   return schedule(() {
     var paths = _requestedPaths.toList();
     _requestedPaths.clear();
     return paths;
   }, "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);
 
   _hasServer = true;
 
   schedule(() {
     return _closeServer().then((_) {
       return shelf_io.serve((request) {
         currentSchedule.heartbeat();
         var path = request.url.path.replaceFirst("/", "");
         _requestedPaths.add(path);
 
         return validateStream(baseDir.load(path))
             .then((stream) => new shelf.Response.ok(stream))
             .catchError((error) {
           return new shelf.Response.notFound('File "$path" not found.');
         });
       }, 'localhost', 0).then((server) {
         _server = server;
         _portCompleter.complete(_server.port);
         currentSchedule.onComplete.schedule(_closeServer);
       });
     });
   }, '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();
   _server = null;
   _hasServer = false;
   _portCompleterCache = null;
   return future;
 }
 
 /// `true` if the current test spins up an HTTP server.
 bool _hasServer = false;
 
 /// The [d.DirectoryDescriptor] describing the server layout of `/api/packages`
 /// on the test server.
 ///
 /// This contains metadata for packages that are being served via
 /// [servePackages]. It's `null` if [servePackages] has not yet been called for
 /// this test.
 d.DirectoryDescriptor _servedApiPackageDir;
 
 /// The [d.DirectoryDescriptor] describing the server layout of `/packages` on
 /// the test server.
 ///
 /// This contains the tarballs for packages that are being served via
 /// [servePackages]. It's `null` if [servePackages] has not yet been called for
 /// 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.
 ///
 /// If [replace] is false, subsequent calls to [servePackages] will add to the
 /// set of packages that are being served. Previous packages will continue to be
 /// served. Otherwise, the previous packages will no longer be served.
 void servePackages(List<Map> pubspecs, {bool replace: false}) {
   if (_servedPackages == null || _servedPackageDir == null) {
     _servedPackages = <String, List<Map>>{};
     _servedApiPackageDir = d.dir('packages', []);
@@ skipping 52 matching lines @@
   }, 'initializing the package server');
 }
 
 /// Converts [value] into a YAML string.
 String yaml(value) => JSON.encode(value);
 
 /// The full path to the created sandbox directory for an integration test.
 String get sandboxDir => _sandboxDir;
 String _sandboxDir;
 
-/// 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";
 
 /// Set to true when the current batch of scheduled events should be aborted.
 bool _abortScheduled = false;
 
 /// Enum identifying a pub command that can be run with a well-defined success
 /// output.
 class RunCommand {
   static final get = new RunCommand('get', new RegExp(r'Got dependencies!$'));
   static final upgrade = new RunCommand('upgrade', new RegExp(
       r'(No dependencies changed\.|Changed \d+ dependenc(y|ies)!)$'));
 
   final String name;
   final RegExp success;
   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
 /// with both commands.
 void forBothPubGetAndUpgrade(void callback(RunCommand command)) {
   group(RunCommand.get.name, () => callback(RunCommand.get));
   group(RunCommand.upgrade.name, () => callback(RunCommand.upgrade));
 }
 
 /// Schedules an invocation of pub [command] and validates that it completes
@@ skipping 29 matching lines @@
 
 void pubGet({Iterable<String> args, error, warning}) {
   pubCommand(RunCommand.get, args: args, error: error, warning: warning);
 }
 
 void pubUpgrade({Iterable<String> args, output, error, warning}) {
   pubCommand(RunCommand.upgrade, args: args, output: output, error: error,
       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);
 
 /// Like [integration], but causes only this test to run.
 void solo_integration(String description, void body()) =>
   _integration(description, body, solo_test);
 
 void _integration(String description, void body(), [Function testFn]) {
   testFn(description, () {
     // TODO(nweiz): remove this when issue 15362 is fixed.
@@ skipping 90 matching lines @@
 /// Any futures in [args] will be resolved before the process is started.
 ScheduledProcess startPublish(ScheduledServer server, {List args}) {
   var tokenEndpoint = server.url.then((url) =>
       url.resolve('/token').toString());
   if (args == null) args = [];
   args = flatten(['lish', '--server', tokenEndpoint, args]);
   return startPub(args: args, tokenEndpoint: tokenEndpoint);
 }
 
 /// 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) {
   // TODO(rnystrom): This is overly specific and inflexible regarding different
   // test packages. Should validate this a little more loosely.
   pub.stdout.expect(startsWith('Publishing test_pkg 1.0.0 to '));
   pub.stdout.expect(emitsLines(
       "|-- LICENSE\n"
       "|-- lib\n"
       "|   '-- test_pkg.dart\n"
@@ skipping 158 matching lines @@
 void ensureGit() {
   if (Platform.operatingSystem == "windows") {
     currentSchedule.timeout = new Duration(seconds: 30);
   }
 
   if (!gitlib.isInstalled) {
     throw new Exception("Git must be installed to run this test.");
   }
 }
 
-/// 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;
 /// each package listed here and all its dependencies will be linked to the
 /// version in the Dart repo.
 ///
 /// [hosted] is a list of package names to version strings for dependencies on
 /// hosted packages.
 void createLockFile(String package, {Iterable<String> sandbox,
     Iterable<String> pkg, Map<String, String> hosted}) {
@@ skipping 53 matching lines @@
   }
 
   var sources = new SourceRegistry();
   sources.register(new HostedSource());
   sources.register(new PathSource());
 
   d.file(path.join(package, 'pubspec.lock'),
       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.
 void useMockClient(MockClient client) {
   var oldInnerClient = httpClient.inner;
   httpClient.inner = client;
   currentSchedule.onComplete.schedule(() {
     httpClient.inner = oldInnerClient;
   }, 'de-activating the mock client');
 }
@@ skipping 127 matching lines @@
     failures.add(actualText);
   }
 
   // Match against the expectation.
   expect(actual, expected);
 }
 
 /// 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(() {
     var cache = new SystemCache.withSources(path.join(sandboxDir, cachePath));
 
     return syncFuture(() {
       var validator = fn(new Entrypoint(path.join(sandboxDir, appPath), cache));
       return validator.validate().then((_) {
         return new Pair(validator.errors, validator.warnings);
       });
@@ skipping 17 matching lines @@
         _lastMatcher.matches(item.last, matchState);
   }
 
   Description describe(Description description) {
     return description.addAll("(", ", ", ")", [_firstMatcher, _lastMatcher]);
   }
 }
 
 /// A [StreamMatcher] that matches multiple lines of output.
 StreamMatcher emitsLines(String output) => inOrder(output.split("\n"));