Clean up the semantics of package descriptions.

lib/src/package.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.
 
 library pub.package;
 
 import 'dart:io';
 
 import 'package:barback/barback.dart';
 import 'package:path/path.dart' as p;
@@ skipping 322 matching lines @@
     if (isMagic) return name;
     return "$name from $source";
   }
 
   /// Returns a [PackageRef] with this one's [name], [source], and
   /// [description].
   PackageRef toRef() => isMagic
       ? new PackageRef.magic(name)
       : new PackageRef(name, source, description);
 
-  /// Returns a [PackageId] for this package with the given concrete version.
-  PackageId atVersion(Version version) =>
-    new PackageId(name, source, version, description);
-
   /// Returns a [PackageDep] for this package with the given version constraint.
   PackageDep withConstraint(VersionConstraint constraint) =>
     new PackageDep(name, source, constraint, description);
 }
 
 /// A reference to a [Package], but not any particular version(s) of it.
 class PackageRef extends _PackageName {
+  /// Creates a reference to a package with the given [name], [source], and
+  /// [description].
+  ///
+  /// Since an ID's description is an implementation detail of its source, this
+  /// should generally not be called outside of [Source] subclasses. A reference
+  /// can be obtained from a user-supplied description using [Source.parseRef].
   PackageRef(String name, String source, description)
       : super(name, source, description);
 
   /// Creates a reference to a magic package (see [isMagic]).
   PackageRef.magic(String name)
       : super.magic(name);
 
   int get hashCode => name.hashCode ^ source.hashCode;
 
   bool operator ==(other) {
     // TODO(rnystrom): We're assuming here that we don't need to delve into the
     // description.
     return other is PackageRef &&
            other.name == name &&
            other.source == source;
   }
 }
 
 /// 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
-/// package may be available from multiple sources. As far as Pub is concerned,
-/// those packages are different.
+/// It's possible for multiple distinct package IDs to point to different
+/// packages that have identical contents. For example, the same package may be
+/// available from multiple sources. As far as Pub is concerned, those packages
+/// are different.
+///
+/// Note that a package ID's [description] field has a different structure than
+/// the [PackageRef.description] or [PackageDep.description] fields for some
+/// sources. For example, the `git` source adds revision information to the
+/// description to ensure that the same ID always points to the same source.
 class PackageId extends _PackageName {
   /// The package's version.
   final Version version;
 
+  /// Creates an ID for a package with the given [name], [source], [version],
+  /// and [description].
+  ///
+  /// Since an ID's description is an implementation detail of its source, this
+  /// should generally not be called outside of [Source] subclasses.
   PackageId(String name, String source, this.version, description)
       : super(name, source, description);
 
   /// Creates an ID for a magic package (see [isMagic]).
   PackageId.magic(String name)
       : super.magic(name),
         version = Version.none;
 
   /// Creates an ID for the given root package.
   PackageId.root(Package package)
@@ skipping 16 matching lines @@
     if (isMagic) return name;
     return "$name $version from $source";
   }
 }
 
 /// A reference to a constrained range of versions of one package.
 class PackageDep extends _PackageName {
   /// The allowed package versions.
   final VersionConstraint constraint;
 
+  /// Creates a reference to package with the given [name], [source],
+  /// [constraint], and [description].
+  ///
+  /// Since an ID's description is an implementation detail of its source, this
+  /// should generally not be called outside of [Source] subclasses.
   PackageDep(String name, String source, this.constraint, description)
       : super(name, source, description);
 
   PackageDep.magic(String name)
       : super.magic(name),
         constraint = Version.none;
 
   String toString() {
     if (isRoot) return "$name $constraint (root)";
     if (isMagic) return name;
     return "$name $constraint from $source ($description)";
   }
 
   int get hashCode => name.hashCode ^ source.hashCode;
 
   bool operator ==(other) {
     // TODO(rnystrom): We're assuming here that we don't need to delve into the
     // description.
     return other is PackageDep &&
            other.name == name &&
            other.source == source &&
            other.constraint == constraint;
   }
 }