net/url: clarify that RawPath is optionally set

Fixes #29662

Change-Id: I38b52b96712e44a323333da17dbbc883516773b6
Reviewed-on: https://go-review.googlesource.com/c/go/+/177900
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

1 files changed, 5 insertions, 4 deletions

diff --git a/src/net/url/url.go b/src/net/url/url.go
index 9ff707b24e..7f6ff93ce4 100644
--- a/src/net/url/url.go
+++ b/src/net/url/url.go
@@ -337,10 +337,11 @@ func escape(s string, mode encoding) string {
 // Note that the Path field is stored in decoded form: /%47%6f%2f becomes /Go/.
 // A consequence is that it is impossible to tell which slashes in the Path were
 // slashes in the raw URL and which were %2f. This distinction is rarely important,
-// but when it is, code must not use Path directly.
-// The Parse function sets both Path and RawPath in the URL it returns,
-// and URL's String method uses RawPath if it is a valid encoding of Path,
-// by calling the EscapedPath method.
+// but when it is, the code should use RawPath, an optional field which only gets
+// set if the default encoding is different from Path.
+//
+// URL's String method uses the EscapedPath method to obtain the path. See the
+// EscapedPath method for more details.
 type URL struct {
 	Scheme     string
 	Opaque     string    // encoded opaque data