net/url: document Parse more

That Parse doesn't parse ("foo.com/path" or "foo.com:443/path") has
become something of a FAQ.

Updates #19779
Updates #21415
Updates #22955

Change-Id: Ib68efddb67f59b1374e8ed94effd4a326988dee7
Reviewed-on: https://go-review.googlesource.com/81436
Reviewed-by: Ian Lance Taylor <iant@golang.org>

diff --git a/src/net/url/url.go b/src/net/url/url.go
index bb44be31171483d90c20905cb2d6517f3d57630c..b2de6d63194d9519450c134dae2a3692001024b5 100644 (file)
--- a/src/net/url/url.go
+++ b/src/net/url/url.go
@@ -441,7 +441,11 @@ func split(s string, c string, cutc bool) (string, string) {
 }
 
 // Parse parses rawurl into a URL structure.
-// The rawurl may be relative or absolute.
+//
+// The rawurl may be relative (a path, without a host) or absolute
+// (starting with a scheme). Trying to parse a hostname and path
+// without a scheme is invalid but may not necessarily return an
+// error, due to parsing ambiguities.
 func Parse(rawurl string) (*URL, error) {
        // Cut off #frag
        u, frag := split(rawurl, "#", true)