Remove API documentation from path README.

pkg/path/lib/path.dart

Index: pkg/path/lib/path.dart
diff --git a/pkg/path/lib/path.dart b/pkg/path/lib/path.dart
index bb88953f36c0f2e13c25d46ade9ab8d6e3184835..e226ec73fb3198839f03f1341eebe2e68c821366 100644
--- a/pkg/path/lib/path.dart
+++ b/pkg/path/lib/path.dart
@@ -18,6 +18,32 @@
 ///
 /// [pub]: http://pub.dartlang.org
 /// [pkg]: http://pub.dartlang.org/packages/path
+///
+/// ## Usage ##
+///
+/// The path library was designed to be imported with a prefix, though you don't
+/// have to if you don't want to:
+///
+///     import 'package:path/path.dart' as path;
+///
+/// The most common way to use the library is through the top-level functions.
+/// These manipulate path strings based on your current working directory and
+/// the path style (POSIX, Windows, or URLs) of the host platform. For example:
+///
+///     path.join("directory", "file.txt");
+///
+/// This calls the top-level [join()] function to join "directory" and
+/// "file.txt" using the current platform's directory separator.
+///
+/// If you want to work with paths for a specific platform regardless of the
+/// underlying platform that the program is running on, you can create a
+/// [Builder] and give it an explicit [Style]:
+///
+///     var builder = new path.Builder(style: Style.windows);
+///     builder.join("directory", "file.txt");
+///
+/// This will join "directory" and "file.txt" using the Windows path separator,
+/// even when the program is run on a POSIX machine.
 library path;
 
 @MirrorsUsed(targets: 'dart.dom.html.window, '
@@ -67,8 +93,8 @@ String get current {
   }
 }
 
-/// Gets the path separator for the current platform. On Mac and Linux, this
-/// is `/`. On Windows, it's `\`.
+/// Gets the path separator for the current platform. This is `\` on Windows
+/// and `/` on other platforms (including the browser).
 String get separator => _builder.separator;
 
 /// Converts [path] to an absolute path by resolving it relative to the current
@@ -765,9 +791,10 @@ class Builder {
   ///       // -> Uri.parse('http://dartlang.org/path/to/foo')
   Uri toUri(String path) {
     if (isRelative(path)) {
-      return Uri.parse(path.replaceAll(style.separatorPattern, '/'));
+      var parsed = _parse(path);
+      return style.relativePathToUri(parsed.parts);
     } else {
-      return style.pathToUri(join(root, path));
+      return style.absolutePathToUri(join(root, path));
     }
   }
 
@@ -821,8 +848,8 @@ abstract class Style {
   // just the "\\".
   static final windows = new _WindowsStyle();
 
-  /// URLs aren't filesystem paths, but they're supported by Pathos to make it
-  /// easier to manipulate URL paths in the browser.
+  /// URLs aren't filesystem paths, but they're supported to make it easier to
+  /// manipulate URL paths in the browser.
   ///
   /// URLs use "/" (forward slash) as separators. Absolute paths either start
   /// with a protocol and optional hostname (e.g. `http://dartlang.org`,
@@ -885,11 +912,11 @@ abstract class Style {
   /// Returns the path represented by [uri] in this style.
   String pathFromUri(Uri uri);
 
-  /// Returns the URI that represents [path].
-  ///
-  /// Pathos will always path an absolute path for [path]. Relative paths are
-  /// handled automatically by [Builder].
-  Uri pathToUri(String path);
+  /// Returns the URI that represents the relative path made of [parts].
+  Uri relativePathToUri(Iterable<String> parts) => new Uri(pathSegments: parts);
+
+  /// Returns the URI that represents [path], which is assumed to be absolute.
+  Uri absolutePathToUri(String path);
 
   String toString() => name;
 }
@@ -913,7 +940,7 @@ class _PosixStyle extends Style {
     throw new ArgumentError("Uri $uri must have scheme 'file:'.");
   }
 
-  Uri pathToUri(String path) {
+  Uri absolutePathToUri(String path) {
     var parsed = _builder._parse(path);
 
     if (parsed.parts.isEmpty) {
@@ -960,7 +987,7 @@ class _WindowsStyle extends Style {
     return Uri.decodeComponent(path.replaceAll("/", "\\"));
   }
 
-  Uri pathToUri(String path) {
+  Uri absolutePathToUri(String path) {
     var parsed = _builder._parse(path);
     if (parsed.root == r'\\') {
       // Network paths become "file://hostname/path/to/file".
@@ -1013,7 +1040,14 @@ class _UrlStyle extends Style {
 
   String pathFromUri(Uri uri) => uri.toString();
 
-  Uri pathToUri(String path) => Uri.parse(path);
+  Uri relativePathToUri(Iterable<String> parts) {
+    // Since [parts] is itself from a URI, it may contain percent-encoded
+    // components. We don't want to double percent-encode them, so we
+    // percent-decode first.
+    return super.relativePathToUri(parts.map(Uri.decodeComponent));
+  }
+
+  Uri absolutePathToUri(String path) => Uri.parse(path);
 }
 
 // TODO(rnystrom): Make this public?