net/http: make Request.WithContext documentation less prescriptive

WithContext makes a shallow copy of a Request, and Clone makes a
deep copy. Both set the context of the new request. The distinction
between the two is clear, and it doesn't seem useful or necessary
to say that "it's rare to need WithContext".

Also update a couple locations that mention WithContext to mention
Clone as well.

Fixes #53413.

Change-Id: I89e6ddebd7d5ca6573e522fe48cd7f50cc645cdd
Reviewed-on: https://go-review.googlesource.com/c/go/+/412778
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
Reviewed-by: Robert Findley <rfindley@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>
Run-TryBot: Damien Neil <dneil@google.com>

diff --git a/src/net/http/request.go b/src/net/http/request.go
index cead91d3d4471c168631bc9a62048584e307597a..5439cb364661565d2a03816bd23713d8bcdadb29 100644 (file)
--- a/src/net/http/request.go
+++ b/src/net/http/request.go
@@ -317,14 +317,14 @@ type Request struct {
        Response *Response
 
        // ctx is either the client or server context. It should only
-       // be modified via copying the whole Request using WithContext.
+       // be modified via copying the whole Request using Clone or WithContext.
        // It is unexported to prevent people from using Context wrong
        // and mutating the contexts held by callers of the same request.
        ctx context.Context
 }
 
 // Context returns the request's context. To change the context, use
-// WithContext.
+// Clone or WithContext.
 //
 // The returned context is always non-nil; it defaults to the
 // background context.
@@ -349,9 +349,7 @@ func (r *Request) Context() context.Context {
 // sending the request, and reading the response headers and body.
 //
 // To create a new request with a context, use NewRequestWithContext.
-// To change the context of a request, such as an incoming request you
-// want to modify before sending back out, use Request.Clone. Between
-// those two uses, it's rare to need WithContext.
+// To make a deep copy of a request with a new context, use Request.Clone.
 func (r *Request) WithContext(ctx context.Context) *Request {
        if ctx == nil {
                panic("nil context")