Fix Path.relativeTo and add support for relative paths as input.

sdk/lib/io/path.dart

Index: sdk/lib/io/path.dart
diff --git a/sdk/lib/io/path.dart b/sdk/lib/io/path.dart
index 751b4792c6f12ac67f1c2279412174c6355ddcf9..c59017ad27dab3e49947dce0cf8fb1dc379fd260 100644
--- a/sdk/lib/io/path.dart
+++ b/sdk/lib/io/path.dart
@@ -7,7 +7,8 @@ part of dart.io;
 /**
  * A Path is an immutable wrapper of a String, with additional member functions
  * for useful path manipulations and queries.
- * On the Windows platform, Path also converts from and to native paths.
+ * On the Windows platform, Path also converts from native paths to paths using
+ * '/' as a path separator, and vice versa.
  *
  * Joining of paths and path normalization handle '.' and '..' in the usual way.
  */
@@ -23,7 +24,7 @@ abstract class Path {
    *
    *     new Path(r'c:\a\b').toString() == '/c:/a/b'
    *
-   * A path starting with '/c:/' (or any other character instead of 'c') is
+   * A path starting with a drive letter is
    * treated specially.  Backwards links ('..') cannot cancel the drive letter.
    *
    * If the path is a share path this is recorded in the Path object and
@@ -50,7 +51,9 @@ abstract class Path {
   bool get isEmpty;
 
   /**
-   * Is this path an absolute path, beginning with a path separator?
+   * Is this path an absolute path, beginning with a '/'?  Note that
+   * Windows paths beginning with '\' or with a drive letter are absolute,
+   * and a leading '/' is added when they are converted to a Path.
    */
   bool get isAbsolute;
 
@@ -60,12 +63,12 @@ abstract class Path {
   bool get isWindowsShare;
 
   /**
-   * Does this path end with a path separator?
+   * Does this path end with a '/'?
    */
   bool get hasTrailingSeparator;
 
   /**
-   * Does this path contain no consecutive path separators, no segments that
+   * Does this path contain no consecutive '/'s, no segments that
    * are '.' unless the path is exactly '.', and segments that are '..' only
    * as the leading segments on a relative path?
    */
@@ -74,7 +77,7 @@ abstract class Path {
   /**
    * Make a path canonical by dropping segments that are '.', cancelling
    * segments that are '..' with preceding segments, if possible,
-   * and combining consecutive path separators.  Leading '..' segments
+   * and combining consecutive '/'s.  Leading '..' segments
    * are kept on relative paths, and dropped from absolute paths.
    */
   Path canonicalize();
@@ -83,7 +86,7 @@ abstract class Path {
    * Joins the relative path [further] to this path.  Canonicalizes the
    * resulting joined path using [canonicalize],
    * interpreting '.' and '..' as directory traversal commands, and removing
-   * consecutive path separators.
+   * consecutive '/'s.
    *
    * If [further] is an absolute path, an IllegalArgument exception is thrown.
    *
@@ -98,8 +101,9 @@ abstract class Path {
    *   containing `'a/b/e'`.
    *
    * Note that the join operation does not drop the last segment of the
-   * base path, the way URL joining does.  That would be accomplished with
-   * basepath.directoryPath.join(further).
+   * base path, the way URL joining does.  To join basepath to further using
+   * URL semantics, use
+   *    [:basepath.directoryPath.join(further):].
    *
    * If you want to avoid joins that traverse
    * parent directories in the base, you can check whether
@@ -114,16 +118,21 @@ abstract class Path {
    * Throws an exception if such a path is impossible.
    * For example, if [base] is '../../a/b' and [this] is '.'.
    * The computation is independent of the file system and current directory.
+   *
+   * To compute a relative path using URL semantics, where the final
+   * path component of the base is dropped unless it ends with a slash,
+   * call [: a.relativeTo(b.directoryPath) :] instead of [: a.relativeTo(b) :].
    */
   Path relativeTo(Path base);
 
   /**
    * Converts a path to a string using the native filesystem's conventions.
    *
-   * On Windows, converts path separators to backwards slashes, and removes
-   * the leading path separator if the path starts with a drive specification.
+   * On Windows, converts '/'s to backwards slashes, and removes
+   * the leading '/' if the path starts with a drive specification.
    * For most valid Windows paths, this should be the inverse of the
-   * constructor Path.fromNative.
+   * conversion that the constructor new Path() performs.  If the path is
+   * a Windows share, restores the '\\' at the start of the path.
    */
   String toNativePath();
 
@@ -135,10 +144,10 @@ abstract class Path {
   String toString();
 
   /**
-   * Gets the segments of a Path.  Paths beginning or ending with the
-   * path separator do not have leading or terminating empty segments.
-   * Other than that, the segments are just the result of splitting the
-   * path on the path separator.
+   * Gets the segments of a Path. The segments are just the result of
+   * splitting the path on any '/' characters, except that a '/' at the
+   * beginning does not create an empty segment before it, and a '/' at
+   * the end does not create an empty segment after it.
    *
    *     new Path('/a/b/c/d').segments() == ['a', 'b', 'c', d'];
    *     new Path(' foo bar //../') == [' foo bar ', '', '..'];
@@ -146,18 +155,18 @@ abstract class Path {
   List<String> segments();
 
   /**
-   * Appends [finalSegment] to a path as a new segment.  Adds a path separator
+   * Appends [finalSegment] to a path as a new segment.  Adds a '/'
    * between the path and [finalSegment] if the path does not already end in
-   * a path separator.  The path is not canonicalized, and [finalSegment] may
-   * contain path separators.
+   * a '/'.  The path is not canonicalized, and [finalSegment] may
+   * contain '/'s.
    */
   Path append(String finalSegment);
 
   /**
-   * Drops the final path separator and whatever follows it from this Path,
-   * and returns the resulting Path object.  If the only path separator in
+   * Drops the final '/' and whatever follows it from this Path,
+   * and returns the resulting Path object.  If the only '/' in
    * this Path is the first character, returns '/' instead of the empty string.
-   * If there is no path separator in the Path, returns the empty string.
+   * If there is no '/' in the Path, returns the empty string.
    *
    *     new Path('../images/dot.gif').directoryPath == '../images'
    *     new Path('/usr/geoffrey/www/').directoryPath == '/usr/geoffrey/www'
@@ -168,8 +177,8 @@ abstract class Path {
   Path get directoryPath;
 
   /**
-   * The part of the path after the last path separator, or the entire path if
-   * it contains no path separator.
+   * The part of the path after the last '/', or the entire path if
+   * it contains no '/'.
    *
    *     new Path('images/DSC_0027.jpg).filename == 'DSC_0027.jpg'
    *     new Path('users/fred/').filename == ''