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..319b48ba8cbf4910c61c85cf9396272faa565f88 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

[floitsch, 2017/02/07 10:47:15]

I have no idea how to read this. Is this a regexp?
Probably not, but hard to tell. Are the "\" escaped?
I believe they are, but commonmark doesn't seem to require that.

Please add examples, and make sure that `\` really needs to be escaped.

[Lasse Reichstein Nielsen, 2017/02/07 10:54:31]

Not a regexp, it's the character sequence BACKSLASH-BACKLASH-QUESTION-BACKSLASH.
The `\` is a markdown/commonmark escape, and it allows you to escape meaningful
characters.

I haven't checked that it's also needed in ``-quotes, but it was needed before …
and now I have. Backslashes don't need to be escaped in ``-quotes, so I'll have
to undo that.

+   * 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

[floitsch, 2017/02/07 10:47:15]

Why this change?

[Lasse Reichstein Nielsen, 2017/02/07 10:54:31]

Because the Uri class changed recently to escape the first colon of a path if it
would look like a scheme (for URIs with no scheme and no authority).

    * 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