From: Russ Cox <rsc@golang.org>
Date: Mon, 6 Oct 2014 19:49:07 +0000 (-0400)
Subject: net/url: document result of String
X-Git-Tag: go1.4beta1~188
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=5b829cca12d029ca25a363637479373a6583dc93;p=gostls13.git

net/url: document result of String

Fixes #8742.

LGTM=bradfitz
R=golang-codereviews
CC=adg, bradfitz, golang-codereviews, iant
https://golang.org/cl/155910043
---

diff --git a/src/net/url/url.go b/src/net/url/url.go
index 0b32cd7c8a..f167408fab 100644
--- a/src/net/url/url.go
+++ b/src/net/url/url.go
@@ -441,6 +441,24 @@ func parseAuthority(authority string) (user *Userinfo, host string, err error) {
 }
 
 // String reassembles the URL into a valid URL string.
+// The general form of the result is one of:
+//
+//	scheme:opaque
+//	scheme://userinfo@host/path?query#fragment
+//
+// If u.Opaque is non-empty, String uses the first form;
+// otherwise it uses the second form.
+//
+// In the second form, the following rules apply:
+//	- if u.Scheme is empty, scheme: is omitted.
+//	- if u.User is nil, userinfo@ is omitted.
+//	- if u.Host is empty, host/ is omitted.
+//	- if u.Scheme and u.Host are empty and u.User is nil,
+//	   the entire scheme://userinfo@host/ is omitted.
+//	- if u.Host is non-empty and u.Path begins with a /,
+//	   the form host/path does not add its own /.
+//	- if u.RawQuery is empty, ?query is omitted.
+//	- if u.Fragment is empty, #fragment is omitted.
 func (u *URL) String() string {
 	var buf bytes.Buffer
 	if u.Scheme != "" {