net/http: mention NewRequestWithContext+Client.Do for custom contexts

Adds mentions of NewRequestWithContext and *Client.Do as prescriptions
for how to use a specified context.Context, to the docs of:
* (*Client).Get
* (*Client).Head
* (*Client).Post
* (*Client).PostForm
* Get
* Head
* Post
* PostForm

given that we can't remove those convenience functions, nor
change the method signatures, except for Go2.

Fixes #35562

Change-Id: I4859e6757e7f958c9067ac4ef15881cfba7d1f8d
Reviewed-on: https://go-review.googlesource.com/c/go/+/299610
Trust: Emmanuel Odeke <emmanuel@orijtech.com>
Run-TryBot: Emmanuel Odeke <emmanuel@orijtech.com>
TryBot-Result: Go Bot <gobot@golang.org>
Reviewed-by: Damien Neil <dneil@google.com>

diff --git a/src/net/http/client.go b/src/net/http/client.go
index 88e2028bc34904e85629ad8cfa3ac92083ca6529..82e665829e9ffba67b0828c85c000368402c0370 100644 (file)
--- a/src/net/http/client.go
+++ b/src/net/http/client.go
@@ -442,6 +442,9 @@ func basicAuth(username, password string) string {
 //
 // To make a request with custom headers, use NewRequest and
 // DefaultClient.Do.
+//
+// To make a request with a specified context.Context, use NewRequestWithContext
+// and DefaultClient.Do.
 func Get(url string) (resp *Response, err error) {
        return DefaultClient.Get(url)
 }
@@ -466,6 +469,9 @@ func Get(url string) (resp *Response, err error) {
 // Caller should close resp.Body when done reading from it.
 //
 // To make a request with custom headers, use NewRequest and Client.Do.
+//
+// To make a request with a specified context.Context, use NewRequestWithContext
+// and Client.Do.
 func (c *Client) Get(url string) (resp *Response, err error) {
        req, err := NewRequest("GET", url, nil)
        if err != nil {
@@ -821,6 +827,9 @@ func defaultCheckRedirect(req *Request, via []*Request) error {
 //
 // See the Client.Do method documentation for details on how redirects
 // are handled.
+//
+// To make a request with a specified context.Context, use NewRequestWithContext
+// and DefaultClient.Do.
 func Post(url, contentType string, body io.Reader) (resp *Response, err error) {
        return DefaultClient.Post(url, contentType, body)
 }
@@ -834,6 +843,9 @@ func Post(url, contentType string, body io.Reader) (resp *Response, err error) {
 //
 // To set custom headers, use NewRequest and Client.Do.
 //
+// To make a request with a specified context.Context, use NewRequestWithContext
+// and Client.Do.
+//
 // See the Client.Do method documentation for details on how redirects
 // are handled.
 func (c *Client) Post(url, contentType string, body io.Reader) (resp *Response, err error) {
@@ -858,6 +870,9 @@ func (c *Client) Post(url, contentType string, body io.Reader) (resp *Response,
 //
 // See the Client.Do method documentation for details on how redirects
 // are handled.
+//
+// To make a request with a specified context.Context, use NewRequestWithContext
+// and DefaultClient.Do.
 func PostForm(url string, data url.Values) (resp *Response, err error) {
        return DefaultClient.PostForm(url, data)
 }
@@ -873,6 +888,9 @@ func PostForm(url string, data url.Values) (resp *Response, err error) {
 //
 // See the Client.Do method documentation for details on how redirects
 // are handled.
+//
+// To make a request with a specified context.Context, use NewRequestWithContext
+// and Client.Do.
 func (c *Client) PostForm(url string, data url.Values) (resp *Response, err error) {
        return c.Post(url, "application/x-www-form-urlencoded", strings.NewReader(data.Encode()))
 }
@@ -888,6 +906,9 @@ func (c *Client) PostForm(url string, data url.Values) (resp *Response, err erro
 //    308 (Permanent Redirect)
 //
 // Head is a wrapper around DefaultClient.Head
+//
+// To make a request with a specified context.Context, use NewRequestWithContext
+// and DefaultClient.Do.
 func Head(url string) (resp *Response, err error) {
        return DefaultClient.Head(url)
 }
@@ -901,6 +922,9 @@ func Head(url string) (resp *Response, err error) {
 //    303 (See Other)
 //    307 (Temporary Redirect)
 //    308 (Permanent Redirect)
+//
+// To make a request with a specified context.Context, use NewRequestWithContext
+// and Client.Do.
 func (c *Client) Head(url string) (resp *Response, err error) {
        req, err := NewRequest("HEAD", url, nil)
        if err != nil {