Update URI related documentation and examples.

sdk/lib/core/uri.dart

Index: sdk/lib/core/uri.dart
diff --git a/sdk/lib/core/uri.dart b/sdk/lib/core/uri.dart
index 7e335b9ff9e8c0895193bad8f66931cb45e87fb6..045449102e5d4d636a3b7e1c00bd5a33104ca3b4 100644
--- a/sdk/lib/core/uri.dart
+++ b/sdk/lib/core/uri.dart
@@ -133,7 +133,7 @@ abstract class Uri {
    *
    * ```
    * // http://example.org/path?q=dart.
-   * new Uri.http("google.com", "/search", { "q" : "dart" });
+   * new Uri.http("example.org", "/path", { "q" : "dart" });
    *
    * // http://user:pass@localhost:8080
    * new Uri.http("user:pass@localhost:8080", "");
@@ -181,23 +181,24 @@ abstract class Uri {
    * This path is interpreted using either Windows or non-Windows
    * semantics.
    *
-   * With non-Windows semantics the slash ("/") is used to separate
-   * path segments.
+   * With non-Windows semantics the slash (`/`) is used to separate
+   * path segments in the input [path].
    *
-   * With Windows semantics, backslash ("\\") and forward-slash ("/")
-   * are used to separate path segments, except if the path starts
-   * with "\\\\?\\" in which case, only backslash ("\\") separates path
-   * segments.
+   * With Windows semantics, backslash (`\`) and forward-slash (`/`)
+   * are used to separate path segments in the input [path],
+   * except if the path starts with `\\?\` in which case
+   * only backslash (`\`) separates path segments in [path].
    *
-   * If the path starts with a path separator an absolute URI is
-   * created. Otherwise a relative URI is created. One exception from
-   * this rule is that when Windows semantics is used and the path
-   * starts with a drive letter followed by a colon (":") and a
-   * path separator then an absolute URI is created.
+   * If the path starts with a path separator, an absolute URI (with the
+   * `file` scheme and an empty authority) is created.
+   * Otherwise a relative URI reference with no scheme or authority is created.
+   * One exception from this rule is that when Windows semantics is used
+   * and the path starts with a drive letter followed by a colon (":") and a
+   * path separator, then an absolute URI is created.
    *
    * The default for whether to use Windows or non-Windows semantics
    * determined from the platform Dart is running on. When running in
-   * the standalone VM this is detected by the VM based on the
+   * the standalone VM, this is detected by the VM based on the
    * operating system. When running in a browser non-Windows semantics
    * is always used.
    *
@@ -220,7 +221,7 @@ abstract class Uri {
    * // file:///xxx/yyy/
    * new Uri.file("/xxx/yyy/", windows: false);
    *
-   * // C:
+   * // C%3A
    * new Uri.file("C:", windows: false);
    * ```
    *
@@ -242,7 +243,8 @@ abstract class Uri {
    * // file:///C:/xxx/yyy
    * new Uri.file(r"C:\xxx\yyy", windows: true);
    *
-   * // This throws an error. A path with a drive letter is not absolute.
+   * // This throws an error. A path with a drive letter, but no following
+   * // path, is not allowed.
    * new Uri.file(r"C:", windows: true);
    *
    * // This throws an error. A path with a drive letter is not absolute.
@@ -252,7 +254,7 @@ abstract class Uri {
    * new Uri.file(r"\\server\share\file", windows: true);
    * ```
    *
-   * If the path passed is not a legal file path [ArgumentError] is thrown.
+   * If the path passed is not a valid file path, an error is thrown.
    */
   factory Uri.file(String path, {bool windows}) = _Uri.file;
 
@@ -578,7 +580,7 @@ abstract class Uri {
    *     Uri.parse("xxx/yyy");  // xxx\yyy
    *     Uri.parse("xxx/yyy/");  // xxx\yyy\
    *     Uri.parse("file:///xxx/yyy");  // \xxx\yyy
-   *     Uri.parse("file:///xxx/yyy/");  // \xxx\yyy/
+   *     Uri.parse("file:///xxx/yyy/");  // \xxx\yyy\
    *     Uri.parse("file:///C:/xxx/yyy");  // C:\xxx\yyy
    *     Uri.parse("file:C:xxx/yyy");  // Throws as a path segment
    *                                   // cannot contain colon on Windows.
@@ -635,10 +637,10 @@ abstract class Uri {
    *
    *     Uri uri1 = Uri.parse("a://b@c:4/d/e?f#g");
    *     Uri uri2 = uri1.replace(scheme: "A", path: "D/E/E", fragment: "G");
-   *     print(uri2);  // prints "A://b@c:4/D/E/E/?f#G"
+   *     print(uri2);  // prints "a://b@c:4/D/E/E?f#G"
    *
    * This method acts similarly to using the `new Uri` constructor with
-   * some of the arguments taken from this `Uri` . Example:
+   * some of the arguments taken from this `Uri`. Example:
    *
    *     Uri uri3 = new Uri(
    *         scheme: "A",
@@ -648,7 +650,7 @@ abstract class Uri {
    *         path: "D/E/E",
    *         query: uri1.query,
    *         fragment: "G");
-   *     print(uri3);  // prints "A://b@c:4/D/E/E/?f#G"
+   *     print(uri3);  // prints "a://b@c:4/D/E/E?f#G"
    *     print(uri2 == uri3);  // prints true.
    *
    * Using this method can be seen as a shorthand for the `Uri` constructor