Convert /** comments to /// in pub.

utils/pub/io.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.
 
-/**
- * Helper functionality to make working with IO easier.
- */
+/// Helper functionality to make working with IO easier.
 library io;
 
 import 'dart:io';
 import 'dart:isolate';
 import 'dart:json';
 import 'dart:uri';
 
 import '../../pkg/path/lib/path.dart' as path;
 import 'log.dart' as log;
 import 'utils.dart';
 
 bool _isGitInstalledCache;
 
 /// The cached Git command.
 String _gitCommandCache;
 
 final NEWLINE_PATTERN = new RegExp("\r\n?|\n\r?");
 
-/**
- * Joins a number of path string parts into a single path. Handles
- * platform-specific path separators. Parts can be [String], [Directory], or
- * [File] objects.
- */
+/// Joins a number of path string parts into a single path. Handles
+/// platform-specific path separators. Parts can be [String], [Directory], or
+/// [File] objects.
 String join(part1, [part2, part3, part4, part5, part6, part7, part8]) {
   var parts = [part1, part2, part3, part4, part5, part6, part7, part8]
       .map((part) => part == null ? null : _getPath(part));
 
   return path.join(parts[0], parts[1], parts[2], parts[3], parts[4], parts[5],
       parts[6], parts[7]);
 }
 
 /// Gets the basename, the file name without any leading directory path, for
 /// [file], which can either be a [String], [File], or [Directory].
 String basename(file) => path.basename(_getPath(file));
 
 /// Gets the the leading directory path for [file], which can either be a
 /// [String], [File], or [Directory].
 String dirname(file) => path.dirname(_getPath(file));
 
 /// Splits [entry] into its individual components.
 List<String> splitPath(entry) => path.split(_getPath(entry));
 
 /// Returns whether or not [entry] is nested somewhere within [dir]. This just
 /// performs a path comparison; it doesn't look at the actual filesystem.
 bool isBeneath(entry, dir) {
   var relative = relativeTo(entry, dir);
   return !path.isAbsolute(relative) && splitPath(relative)[0] != '..';
 }
 
 /// Returns the path to [target] from [base].
 String relativeTo(target, base) => path.relative(target, from: base);
 
-/**
- * Asynchronously determines if [path], which can be a [String] file path, a
- * [File], or a [Directory] exists on the file system. Returns a [Future] that
- * completes with the result.
- */
+/// Asynchronously determines if [path], which can be a [String] file path, a
+/// [File], or a [Directory] exists on the file system. Returns a [Future] that
+/// completes with the result.
 Future<bool> exists(path) {
   path = _getPath(path);
   return Futures.wait([fileExists(path), dirExists(path)]).transform((results) {
     return results[0] || results[1];
   });
 }
 
-/**
- * Asynchronously determines if [file], which can be a [String] file path or a
- * [File], exists on the file system. Returns a [Future] that completes with
- * the result.
- */
+/// Asynchronously determines if [file], which can be a [String] file path or a
+/// [File], exists on the file system. Returns a [Future] that completes with
+/// the result.
 Future<bool> fileExists(file) {
   var path = _getPath(file);
   return log.ioAsync("Seeing if file $path exists.",
       new File(path).exists(),
       (exists) => "File $path ${exists ? 'exists' : 'does not exist'}.");
 }
 
-/**
- * Reads the contents of the text file [file], which can either be a [String] or
- * a [File].
- */
+/// Reads the contents of the text file [file], which can either be a [String]
+/// or a [File].
 Future<String> readTextFile(file) {
   var path = _getPath(file);
   return log.ioAsync("Reading text file $path.",
       new File(path).readAsString(Encoding.UTF_8),
       (contents) {
         // Sanity check: don't spew a huge file.
         if (contents.length < 1024 * 1024) {
           return "Read $path. Contents:\n$contents";
         } else {
           return "Read ${contents.length} characters from $path.";
         }
       });
 }
 
-/**
- * Creates [file] (which can either be a [String] or a [File]), and writes
- * [contents] to it. Completes when the file is written and closed.
- *
- * If [dontLogContents] is true, the contents of the file will never be logged.
- */
+/// Creates [file] (which can either be a [String] or a [File]), and writes
+/// [contents] to it. Completes when the file is written and closed.
+///
+/// If [dontLogContents] is true, the contents of the file will never be logged.
 Future<File> writeTextFile(file, String contents, {dontLogContents: false}) {
   var path = _getPath(file);
   file = new File(path);
 
   // Sanity check: don't spew a huge file.
   log.io("Writing ${contents.length} characters to text file $path.");
   if (!dontLogContents && contents.length < 1024 * 1024) {
     log.fine("Contents:\n$contents");
   }
 
   return file.open(FileMode.WRITE).chain((opened) {
     return opened.writeString(contents).chain((ignore) {
         return opened.close().transform((_) {
           log.fine("Wrote text file $path.");
           return file;
         });
     });
   });
 }
 
-/**
- * Asynchronously deletes [file], which can be a [String] or a [File]. Returns a
- * [Future] that completes when the deletion is done.
- */
+/// Asynchronously deletes [file], which can be a [String] or a [File]. Returns
+/// a [Future] that completes when the deletion is done.
 Future<File> deleteFile(file) {
   var path = _getPath(file);
   return log.ioAsync("delete file $path",
       new File(path).delete());
 }
 
 /// Writes [stream] to a new file at [path], which may be a [String] or a
 /// [File]. Will replace any file already at that path. Completes when the file
 /// is done being written.
 Future<File> createFileFromStream(InputStream stream, path) {
@@ skipping 26 matching lines @@
       log.fine("Got error after stream was closed: $error");
     }
   }
 
   stream.onError = completeError;
   outputStream.onError = completeError;
 
   return completer.future;
 }
 
-/**
- * Creates a directory [dir]. Returns a [Future] that completes when the
- * directory is created.
- */
+/// Creates a directory [dir]. Returns a [Future] that completes when the
+/// directory is created.
 Future<Directory> createDir(dir) {
   dir = _getDirectory(dir);
   return log.ioAsync("create directory ${dir.path}",
       dir.create());
 }
 
-/**
- * Ensures that [path] and all its parent directories exist. If they don't
- * exist, creates them. Returns a [Future] that completes once all the
- * directories are created.
- */
+/// Ensures that [path] and all its parent directories exist. If they don't
+/// exist, creates them. Returns a [Future] that completes once all the
+/// directories are created.
 Future<Directory> ensureDir(path) {
   path = _getPath(path);
   log.fine("Ensuring directory $path exists.");
   if (path == '.') return new Future.immediate(new Directory('.'));
 
   return dirExists(path).chain((exists) {
     if (exists) {
       log.fine("Directory $path already exists.");
       return new Future.immediate(new Directory(path));
     }
@@ skipping 12 matching lines @@
 
         completer.complete(_getDirectory(path));
         return true;
       });
       future.then(completer.complete);
       return completer.future;
     });
   });
 }
 
-/**
- * Creates a temp directory whose name will be based on [dir] with a unique
- * suffix appended to it. If [dir] is not provided, a temp directory will be
- * created in a platform-dependent temporary location. Returns a [Future] that
- * completes when the directory is created.
- */
+/// Creates a temp directory whose name will be based on [dir] with a unique
+/// suffix appended to it. If [dir] is not provided, a temp directory will be
+/// created in a platform-dependent temporary location. Returns a [Future] that
+/// completes when the directory is created.
 Future<Directory> createTempDir([dir = '']) {
   dir = _getDirectory(dir);
   return log.ioAsync("create temp directory ${dir.path}",
       dir.createTemp());
 }
 
-/**
- * Asynchronously recursively deletes [dir], which can be a [String] or a
- * [Directory]. Returns a [Future] that completes when the deletion is done.
- */
+/// Asynchronously recursively deletes [dir], which can be a [String] or a
+/// [Directory]. Returns a [Future] that completes when the deletion is done.
 Future<Directory> deleteDir(dir) {
   dir = _getDirectory(dir);
 
   return _attemptRetryable(() => log.ioAsync("delete directory ${dir.path}",
       dir.delete(recursive: true)));
 }
 
 /// Asynchronously lists the contents of [dir], which can be a [String]
 /// directory path or a [Directory]. If [recursive] is `true`, lists
 /// subdirectory contents (defaults to `false`). If [includeHiddenFiles] is
@@ skipping 57 matching lines @@
       return Futures.wait(children).transform((childContents) {
         contents.addAll(flatten(childContents));
         return contents;
       });
     });
   }
 
   return doList(_getDirectory(dir), new Set<String>());
 }
 
-/**
- * Asynchronously determines if [dir], which can be a [String] directory path
- * or a [Directory], exists on the file system. Returns a [Future] that
- * completes with the result.
- */
+/// Asynchronously determines if [dir], which can be a [String] directory path
+/// or a [Directory], exists on the file system. Returns a [Future] that
+/// completes with the result.
 Future<bool> dirExists(dir) {
   dir = _getDirectory(dir);
   return log.ioAsync("Seeing if directory ${dir.path} exists.",
       dir.exists(),
       (exists) => "Directory ${dir.path} "
                   "${exists ? 'exists' : 'does not exist'}.");
 }
 
-/**
- * "Cleans" [dir]. If that directory already exists, it will be deleted. Then a
- * new empty directory will be created. Returns a [Future] that completes when
- * the new clean directory is created.
- */
+/// "Cleans" [dir]. If that directory already exists, it will be deleted. Then a
+/// new empty directory will be created. Returns a [Future] that completes when
+/// the new clean directory is created.
 Future<Directory> cleanDir(dir) {
   return dirExists(dir).chain((exists) {
     if (exists) {
       // Delete it first.
       return deleteDir(dir).chain((_) => createDir(dir));
     } else {
       // Just create it.
       return createDir(dir);
     }
   });
@@ skipping 34 matching lines @@
 
       // Wait a bit and try again.
       log.fine("Operation failed, retrying (attempt $attempts).");
       return sleep(500).chain(makeAttempt);
     });
   }
 
   return makeAttempt(null);
 }
 
-/**
- * Creates a new symlink that creates an alias from [from] to [to], both of
- * which can be a [String], [File], or [Directory]. Returns a [Future] which
- * completes to the symlink file (i.e. [to]).
- */
+/// Creates a new symlink that creates an alias from [from] to [to], both of
+/// which can be a [String], [File], or [Directory]. Returns a [Future] which
+/// completes to the symlink file (i.e. [to]).
 Future<File> createSymlink(from, to) {
   from = _getPath(from);
   to = _getPath(to);
 
   log.fine("Create symlink $from -> $to.");
 
   var command = 'ln';
   var args = ['-s', from, to];
 
   if (Platform.operatingSystem == 'windows') {
     // Call mklink on Windows to create an NTFS junction point. Only works on
     // Vista or later. (Junction points are available earlier, but the "mklink"
     // command is not.) I'm using a junction point (/j) here instead of a soft
     // link (/d) because the latter requires some privilege shenanigans that
     // I'm not sure how to specify from the command line.
     command = 'mklink';
     args = ['/j', to, from];
   }
 
   return runProcess(command, args).transform((result) {
     // TODO(rnystrom): Check exit code and output?
     return new File(to);
   });
 }
 
-/**
- * Creates a new symlink that creates an alias from the `lib` directory of
- * package [from] to [to], both of which can be a [String], [File], or
- * [Directory]. Returns a [Future] which completes to the symlink file (i.e.
- * [to]). If [from] does not have a `lib` directory, this shows a warning if
- * appropriate and then does nothing.
- */
+/// Creates a new symlink that creates an alias from the `lib` directory of
+/// package [from] to [to], both of which can be a [String], [File], or
+/// [Directory]. Returns a [Future] which completes to the symlink file (i.e.
+/// [to]). If [from] does not have a `lib` directory, this shows a warning if
+/// appropriate and then does nothing.
 Future<File> createPackageSymlink(String name, from, to,
     {bool isSelfLink: false}) {
   // See if the package has a "lib" directory.
   from = join(from, 'lib');
   return dirExists(from).chain((exists) {
     log.fine("Creating ${isSelfLink ? "self" : ""}link for package '$name'.");
     if (exists) return createSymlink(from, to);
 
     // It's OK for the self link (i.e. the root package) to not have a lib
     // directory since it may just be a leaf application that only has
@@ skipping 80 matching lines @@
   };
 
   stream.onError = (e) {
     removeCallbacks();
     completer.completeException(e, stackTrace);
   };
 
   return completer.future;
 }
 
-/**
- * Takes all input from [source] and writes it to [sink].
- *
- * Returns a future that completes when [source] is closed.
- */
+/// Takes all input from [source] and writes it to [sink].
+///
+/// Returns a future that completes when [source] is closed.
 Future pipeInputToInput(InputStream source, ListInputStream sink) {
   var completer = new Completer();
   source.onClosed = () {
     sink.markEndOfStream();
     completer.complete(null);
   };
   source.onData = () {
     // Even if the sink is closed and we aren't going to do anything with more
     // data, we still need to drain it from source to work around issue 7218.
     var data = source.read();
     try {
       if (!sink.closed) sink.write(data);
     } on StreamException catch (e, stackTrace) {
       // Ignore an exception to work around issue 4222.
       log.io("Writing to an unclosed ListInputStream caused exception $e\n"
           "$stackTrace");
     }
   };
   // TODO(nweiz): propagate this error to the sink. See issue 3657.
   source.onError = (e) { throw e; };
   return completer.future;
 }
 
-/**
- * Buffers all input from an InputStream and returns it as a future.
- */
+/// Buffers all input from an InputStream and returns it as a future.
 Future<List<int>> consumeInputStream(InputStream stream) {
   if (stream.closed) return new Future.immediate(<int>[]);
 
   // TODO(nweiz): remove this when issue 4061 is fixed.
   var stackTrace;
   try {
     throw "";
   } catch (_, localStackTrace) {
     stackTrace = localStackTrace;
   }
@@ skipping 119 matching lines @@
   if (environment != null) {
     options.environment = new Map.from(Platform.environment);
     environment.forEach((key, value) => options.environment[key] = value);
   }
 
   log.process(executable, args);
 
   return fn(executable, args, options);
 }
 
-/**
- * Wraps [input] to provide a timeout. If [input] completes before
- * [milliseconds] have passed, then the return value completes in the same way.
- * However, if [milliseconds] pass before [input] has completed, it completes
- * with a [TimeoutException] with [description] (which should be a fragment
- * describing the action that timed out).
- *
- * Note that timing out will not cancel the asynchronous operation behind
- * [input].
- */
+/// Wraps [input] to provide a timeout. If [input] completes before
+/// [milliseconds] have passed, then the return value completes in the same way.
+/// However, if [milliseconds] pass before [input] has completed, it completes
+/// with a [TimeoutException] with [description] (which should be a fragment
+/// describing the action that timed out).
+///
+/// Note that timing out will not cancel the asynchronous operation behind
+/// [input].
 Future timeout(Future input, int milliseconds, String description) {
   var completer = new Completer();
   var timer = new Timer(milliseconds, (_) {
     if (completer.future.isComplete) return;
     completer.completeException(new TimeoutException(
         'Timed out while $description.'));
   });
   input.handleException((e) {
     if (completer.future.isComplete) return false;
     timer.cancel();
@@ skipping 79 matching lines @@
 
   future.handleException((err) {
     // If the process failed, they probably don't have it.
     completer.complete(false);
     return true;
   });
 
   return completer.future;
 }
 
-/**
- * Extracts a `.tar.gz` file from [stream] to [destination], which can be a
- * directory or a path. Returns whether or not the extraction was successful.
- */
+/// Extracts a `.tar.gz` file from [stream] to [destination], which can be a
+/// directory or a path. Returns whether or not the extraction was successful.
 Future<bool> extractTarGz(InputStream stream, destination) {
   destination = _getPath(destination);
 
   log.fine("Extracting .tar.gz stream to $destination.");
 
   if (Platform.operatingSystem == "windows") {
     return _extractTarGzWindows(stream, destination);
   }
 
   var completer = new Completer<int>();
@@ skipping 145 matching lines @@
       // stderr. We don't want to show that since it's meaningless.
       // TODO(rnystrom): Should log this and display it if an actual error
       // occurs.
       consumeInputStream(process.stderr);
       return pipeInputToInput(process.stdout, stream);
     });
   });
   return stream;
 }
 
-/**
- * Exception thrown when an operation times out.
- */
+/// Exception thrown when an operation times out.
 class TimeoutException implements Exception {
   final String message;
 
   const TimeoutException(this.message);
 
   String toString() => message;
 }
 
-/**
- * Contains the results of invoking a [Process] and waiting for it to complete.
- */
+/// Contains the results of invoking a [Process] and waiting for it to complete.
 class PubProcessResult {
   final List<String> stdout;
   final List<String> stderr;
   final int exitCode;
 
   const PubProcessResult(this.stdout, this.stderr, this.exitCode);
 
   bool get success => exitCode == 0;
 }
 
-/**
- * Gets the path string for [entry], which can either already be a path string,
- * or be a [File] or [Directory]. Allows working generically with "file-like"
- * objects.
- */
+/// Gets the path string for [entry], which can either already be a path string,
+/// or be a [File] or [Directory]. Allows working generically with "file-like"
+/// objects.
 String _getPath(entry) {
   if (entry is String) return entry;
   if (entry is File) return entry.name;
   if (entry is Directory) return entry.path;
   throw 'Entry $entry is not a supported type.';
 }
 
-/**
- * Gets a [Directory] for [entry], which can either already be one, or be a
- * [String].
- */
+/// Gets a [Directory] for [entry], which can either already be one, or be a
+/// [String].
 Directory _getDirectory(entry) {
   if (entry is Directory) return entry;
   return new Directory(entry);
 }
 
-/**
- * Gets a [Uri] for [uri], which can either already be one, or be a [String].
- */
+/// Gets a [Uri] for [uri], which can either already be one, or be a [String].
 Uri _getUri(uri) {
   if (uri is Uri) return uri;
   return new Uri.fromString(uri);
 }