Update URI related documentation and examples.

sdk/lib/core/uri.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.
 
 part of dart.core;
 
 // Frequently used character codes.
 const int _SPACE = 0x20;
 const int _PERCENT = 0x25;
 const int _PLUS = 0x2B;
@@ skipping 115 matching lines @@
                Map<String, dynamic/*String|Iterable<String>*/> queryParameters,
                String fragment}) = _Uri;
 
   /**
    * Creates a new `http` URI from authority, path and query.
    *
    * Examples:
    *
    * ```
    * // 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", "");
    *
    * // http://example.org/a%20b
    * new Uri.http("example.org", "a b");
    *
    * // http://example.org/a%252F
    * new Uri.http("example.org", "/a%2F");
    * ```
@@ skipping 27 matching lines @@
                     [Map<String, String> queryParameters]) = _Uri.https;
 
   /**
    * Creates a new file URI from an absolute or relative file path.
    *
    * The file path is passed in [path].
    *
    * 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.
    *
    * To override the automatic detection of which semantics to use pass
    * a value for [windows]. Passing `true` will use Windows
    * semantics and passing `false` will use non-Windows semantics.
    *
    * Examples using non-Windows semantics:
    *
    * ```
    * // xxx/yyy
    * new Uri.file("xxx/yyy", windows: false);
    *
    * // xxx/yyy/
    * new Uri.file("xxx/yyy/", windows: false);
    *
    * // file:///xxx/yyy
    * new Uri.file("/xxx/yyy", windows: false);
    *
    * // file:///xxx/yyy/
    * new Uri.file("/xxx/yyy/", windows: false);
    *
-   * // C:
+   * // C%3A
    * new Uri.file("C:", windows: false);
    * ```
    *
    * Examples using Windows semantics:
    *
    * ```
    * // xxx/yyy
    * new Uri.file(r"xxx\yyy", windows: true);
    *
    * // xxx/yyy/
    * new Uri.file(r"xxx\yyy\", windows: true);
    *
    * file:///xxx/yyy
    * new Uri.file(r"\xxx\yyy", windows: true);
    *
    * file:///xxx/yyy/
    * new Uri.file(r"\xxx\yyy/", windows: true);
    *
    * // 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.
    * new Uri.file(r"C:xxx\yyy", windows: true);
    *
    * // file://server/share/file
    * 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;
 
   /**
    * Like [Uri.file] except that a non-empty URI path ends in a slash.
    *
    * If [path] is not empty, and it doesn't end in a directory separator,
    * then a slash is added to the returned URI's path.
    * In all other cases, the result is the same as returned by `Uri.file`.
    */
@@ skipping 305 matching lines @@
    *     Uri.parse("file:///xxx/yyy");  // /xxx/yyy
    *     Uri.parse("file:///xxx/yyy/");  // /xxx/yyy/
    *     Uri.parse("file:///C:");  // /C:
    *     Uri.parse("file:///C:a");  // /C:a
    *
    * Examples using Windows semantics (resulting URI in comment):
    *
    *     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.
    *     Uri.parse("file://server/share/file");  // \\server\share\file
    *
    * If the URI is not a file URI calling this throws
    * [UnsupportedError].
    *
    * If the URI cannot be converted to a file path calling this throws
    * [UnsupportedError].
@@ skipping 36 matching lines @@
    * value from this `Uri` instead.
    *
    * This method is different from [Uri.resolve] which overrides in a
    * hierarchical manner,
    * and can instead replace each part of a `Uri` individually.
    *
    * Example:
    *
    *     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",
    *         userInfo: uri1.userInfo,
    *         host: uri1.host,
    *         port: uri1.port,
    *         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
    * call above, but may also be slightly faster because the parts taken
    * from this `Uri` need not be checked for validity again.
    */
   Uri replace({String scheme,
                String userInfo,
                String host,
                int port,
@@ skipping 3904 matching lines @@
   int delta = (text.codeUnitAt(start + 4) ^ _COLON) * 3;
   delta |= text.codeUnitAt(start)     ^ 0x64 /*d*/;
   delta |= text.codeUnitAt(start + 1) ^ 0x61 /*a*/;
   delta |= text.codeUnitAt(start + 2) ^ 0x74 /*t*/;
   delta |= text.codeUnitAt(start + 3) ^ 0x61 /*a*/;
   return delta;
 }
 
 /// Helper function returning the length of a string, or `0` for `null`.
 int _stringOrNullLength(String s) => (s == null) ? 0 : s.length;