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

utils/pub/entrypoint.dart

Index: utils/pub/entrypoint.dart
diff --git a/utils/pub/entrypoint.dart b/utils/pub/entrypoint.dart
index 56007e0fe78dd90ab32c0a88af95cdaae972a4be..1b0717b0415e0e0b651b5168a7dc1ee3d8838060 100644
--- a/utils/pub/entrypoint.dart
+++ b/utils/pub/entrypoint.dart
@@ -14,39 +14,31 @@ import 'utils.dart';
 import 'version.dart';
 import 'version_solver.dart';
 
-/**
- * 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
- * associated with and is responsible for managing the "packages" directory
- * for it.
- *
- * That directory contains symlinks to all packages used by an app. These links
- * point either to the [SystemCache] or to some other location on the local
- * filesystem.
- *
- * While entrypoints are typically applications, a pure library package may end
- * up being used as an entrypoint. Also, a single package may be used as an
- * entrypoint in one context but not in another. For example, a package that
- * contains a reusable library may not be the entrypoint when used by an app,
- * but may be the entrypoint when you're running its tests.
- */
+/// 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
+/// associated with and is responsible for managing the "packages" directory
+/// for it.
+///
+/// That directory contains symlinks to all packages used by an app. These links
+/// point either to the [SystemCache] or to some other location on the local
+/// filesystem.
+///
+/// While entrypoints are typically applications, a pure library package may end
+/// up being used as an entrypoint. Also, a single package may be used as an
+/// entrypoint in one context but not in another. For example, a package that
+/// contains a reusable library may not be the entrypoint when used by an app,
+/// but may be the entrypoint when you're running its tests.
 class Entrypoint {
-  /**
-   * The root package this entrypoint is associated with.
-   */
+  /// The root package this entrypoint is associated with.
   final Package root;
 
-  /**
-   * The system-wide cache which caches packages that need to be fetched over
-   * the network.
-   */
+  /// The system-wide cache which caches packages that need to be fetched over
+  /// the network.
   final SystemCache cache;
 
-  /**
-   * Packages which are either currently being asynchronously installed to the
-   * directory, or have already been installed.
-   */
+  /// Packages which are either currently being asynchronously installed to the
+  /// directory, or have already been installed.
   final Map<PackageId, Future<PackageId>> _installs;
 
   Entrypoint(this.root, this.cache)
@@ -58,25 +50,21 @@ class Entrypoint {
         new Entrypoint(package, cache));
   }
 
-  /**
-   * The path to this "packages" directory.
-   */
+  /// The path to this "packages" directory.
   // TODO(rnystrom): Make this path configurable.

[nweiz, 2012/12/19 20:56:07]

Move this above the doc comment.

[Bob Nystrom, 2012/12/20 02:04:15]

Done.

   String get path => join(root.dir, 'packages');
 
-  /**
-   * Ensures that the package identified by [id] is installed to the directory.
-   * Returns the resolved [PackageId].
-   *
-   * If this completes successfully, the package is guaranteed to be importable
-   * using the `package:` scheme.
-   *
-   * This will automatically install the package to the system-wide cache as
-   * well if it requires network access to retrieve (specifically, if
-   * `id.source.shouldCache` is true).
-   *
-   * See also [installDependencies].
-   */
+  /// Ensures that the package identified by [id] is installed to the directory.
+  /// Returns the resolved [PackageId].
+  ///
+  /// If this completes successfully, the package is guaranteed to be importable
+  /// using the `package:` scheme.
+  ///
+  /// This will automatically install the package to the system-wide cache as
+  /// well if it requires network access to retrieve (specifically, if
+  /// `id.source.shouldCache` is true).
+  ///
+  /// See also [installDependencies].
   Future<PackageId> install(PackageId id) {
     var pendingOrCompleted = _installs[id];
     if (pendingOrCompleted != null) return pendingOrCompleted;
@@ -108,32 +96,26 @@ class Entrypoint {
     return future;
   }
 
-  /**
-   * Installs all dependencies of the [root] package to its "packages"
-   * directory, respecting the [LockFile] if present. Returns a [Future] that
-   * completes when all dependencies are installed.
-   */
+  /// Installs all dependencies of the [root] package to its "packages"
+  /// directory, respecting the [LockFile] if present. Returns a [Future] that
+  /// completes when all dependencies are installed.
   Future installDependencies() {
     return _loadLockFile()
       .chain((lockFile) => resolveVersions(cache.sources, root, lockFile))
       .chain(_installDependencies);
   }
 
-  /**
-   * Installs the latest available versions of all dependencies of the [root]
-   * package to its "package" directory, writing a new [LockFile]. Returns a
-   * [Future] that completes when all dependencies are installed.
-   */
+  /// Installs the latest available versions of all dependencies of the [root]
+  /// package to its "package" directory, writing a new [LockFile]. Returns a
+  /// [Future] that completes when all dependencies are installed.
   Future updateAllDependencies() {
     return resolveVersions(cache.sources, root, new LockFile.empty())
       .chain(_installDependencies);
   }
 
-  /**
-   * Installs the latest available versions of [dependencies], while leaving
-   * other dependencies as specified by the [LockFile] if possible. Returns a
-   * [Future] that completes when all dependencies are installed.
-   */
+  /// Installs the latest available versions of [dependencies], while leaving
+  /// other dependencies as specified by the [LockFile] if possible. Returns a
+  /// [Future] that completes when all dependencies are installed.
   Future updateDependencies(List<String> dependencies) {
     return _loadLockFile().chain((lockFile) {
       var versionSolver = new VersionSolver(cache.sources, root, lockFile);
@@ -144,10 +126,8 @@ class Entrypoint {
     }).chain(_installDependencies);
   }
 
-  /**
-   * Removes the old packages directory, installs all dependencies listed in
-   * [packageVersions], and writes a [LockFile].
-   */
+  /// Removes the old packages directory, installs all dependencies listed in
+  /// [packageVersions], and writes a [LockFile].
   Future _installDependencies(List<PackageId> packageVersions) {
     return cleanDir(path).chain((_) {
       return Futures.wait(packageVersions.map((id) {
@@ -159,13 +139,11 @@ class Entrypoint {
       .chain(_linkSecondaryPackageDirs);
   }
 
-  /**
-   * Loads the list of concrete package versions from the `pubspec.lock`, if it
-   * exists. If it doesn't, this completes to an empty [LockFile].
-   *
-   * If there's an error reading the `pubspec.lock` file, this will print a
-   * warning message and act as though the file doesn't exist.
-   */
+  /// Loads the list of concrete package versions from the `pubspec.lock`, if it
+  /// exists. If it doesn't, this completes to an empty [LockFile].
+  ///
+  /// If there's an error reading the `pubspec.lock` file, this will print a
+  /// warning message and act as though the file doesn't exist.
   Future<LockFile> _loadLockFile() {
     var lockFilePath = join(root.dir, 'pubspec.lock');
 
@@ -181,9 +159,7 @@ class Entrypoint {
     });
   }
 
-  /**
-   * Saves a list of concrete package versions to the `pubspec.lock` file.
-   */
+  /// Saves a list of concrete package versions to the `pubspec.lock` file.
   Future _saveLockFile(List<PackageId> packageIds) {
     var lockFile = new LockFile.empty();
     for (var id in packageIds) {
@@ -195,10 +171,8 @@ class Entrypoint {
     return writeTextFile(lockFilePath, lockFile.serialize());
   }
 
-  /**
-   * Installs a self-referential symlink in the `packages` directory that will
-   * allow a package to import its own files using `package:`.
-   */
+  /// Installs a self-referential symlink in the `packages` directory that will
+  /// allow a package to import its own files using `package:`.
   Future _installSelfReference(_) {
     var linkPath = join(path, root.name);
     return exists(linkPath).chain((exists) {
@@ -210,11 +184,9 @@ class Entrypoint {
     });
   }
 
-  /**
-   * If `bin/`, `test/`, or `example/` directories exist, symlink `packages/`
-   * into them so that their entrypoints can be run. Do the same for any
-   * subdirectories of `test/` and `example/`.
-   */
+  /// If `bin/`, `test/`, or `example/` directories exist, symlink `packages/`
+  /// into them so that their entrypoints can be run. Do the same for any
+  /// subdirectories of `test/` and `example/`.
   Future _linkSecondaryPackageDirs(_) {
     var binDir = join(root.dir, 'bin');
     var exampleDir = join(root.dir, 'example');
@@ -230,10 +202,8 @@ class Entrypoint {
       .chain((_) => _linkSecondaryPackageDirsRecursively(webDir));
   }
 
-  /**
-   * Creates a symlink to the `packages` directory in [dir] and all its
-   * subdirectories.
-   */
+  /// Creates a symlink to the `packages` directory in [dir] and all its
+  /// subdirectories.
   Future _linkSecondaryPackageDirsRecursively(String dir) {
     return dirExists(dir).chain((exists) {
       if (!exists) return new Future.immediate(null);
@@ -251,10 +221,8 @@ class Entrypoint {
   }
 
   // TODO(nweiz): roll this into [listDir] in io.dart once issue 4775 is fixed.
-  /**
-   * Recursively lists the contents of [dir], excluding hidden `.DS_Store` files
-   * and `package` files.
-   */
+  /// Recursively lists the contents of [dir], excluding hidden `.DS_Store`
+  /// files and `package` files.
   Future<List<String>> _listDirWithoutPackages(dir) {
     return listDir(dir).chain((files) {
       return Futures.wait(files.map((file) {
@@ -271,9 +239,7 @@ class Entrypoint {
     }).transform(flatten);
   }
 
-  /**
-   * Creates a symlink to the `packages` directory in [dir] if none exists.
-   */
+  /// Creates a symlink to the `packages` directory in [dir] if none exists.
   Future _linkSecondaryPackageDir(String dir) {
     var to = join(dir, 'packages');
     return exists(to).chain((exists) {