Issue #131: document redirects' following for client functions

client.go

@@ -19,13 +19,15 @@ import (
 // Request must contain at least non-zero RequestURI with full url (including
 // scheme and host) or non-zero Host header + RequestURI.
 //
-// Response is ignored if resp is nil.
-//
 // Client determines the server to be requested in the following order:
 //
 //   - from RequestURI if it contains full url with scheme and host;
 //   - from Host header otherwise.
 //
+// The function doesn't follow redirects. Use Get* for following redirects.
+//
+// Response is ignored if resp is nil.
+//
 // ErrNoFreeConns is returned if all DefaultMaxConnsPerHost connections
 // to the requested host are busy.
 //
@@ -46,6 +48,8 @@ func Do(req *Request, resp *Response) error {
 //   - from RequestURI if it contains full url with scheme and host;
 //   - from Host header otherwise.
 //
+// The function doesn't follow redirects. Use Get* for following redirects.
+//
 // Response is ignored if resp is nil.
 //
 // ErrTimeout is returned if the response wasn't returned during
@@ -68,6 +72,8 @@ func DoTimeout(req *Request, resp *Response, timeout time.Duration) error {
 //   - from RequestURI if it contains full url with scheme and host;
 //   - from Host header otherwise.
 //
+// The function doesn't follow redirects. Use Get* for following redirects.
+//
 // Response is ignored if resp is nil.
 //
 // ErrTimeout is returned if the response wasn't returned until
@@ -81,6 +87,8 @@ func DoDeadline(req *Request, resp *Response, deadline time.Time) error {
 
 // Get appends url contents to dst and returns it as body.
 //
+// The function follows redirects. Use Do* for manually handling redirects.
+//
 // New body buffer is allocated if dst is nil.
 func Get(dst []byte, url string) (statusCode int, body []byte, err error) {
 	return defaultClient.Get(dst, url)
@@ -88,6 +96,8 @@ func Get(dst []byte, url string) (statusCode int, body []byte, err error) {
 
 // GetTimeout appends url contents to dst and returns it as body.
 //
+// The function follows redirects. Use Do* for manually handling redirects.
+//
 // New body buffer is allocated if dst is nil.
 //
 // ErrTimeout error is returned if url contents couldn't be fetched
@@ -98,6 +108,8 @@ func GetTimeout(dst []byte, url string, timeout time.Duration) (statusCode int,
 
 // GetDeadline appends url contents to dst and returns it as body.
 //
+// The function follows redirects. Use Do* for manually handling redirects.
+//
 // New body buffer is allocated if dst is nil.
 //
 // ErrTimeout error is returned if url contents couldn't be fetched
@@ -110,6 +122,8 @@ func GetDeadline(dst []byte, url string, deadline time.Time) (statusCode int, bo
 //
 // Response body is appended to dst, which is returned as body.
 //
+// The function follows redirects. Use Do* for manually handling redirects.
+//
 // New body buffer is allocated if dst is nil.
 //
 // Empty POST body is sent if postArgs is nil.
@@ -216,6 +230,8 @@ type Client struct {
 
 // Get appends url contents to dst and returns it as body.
 //
+// The function follows redirects. Use Do* for manually handling redirects.
+//
 // New body buffer is allocated if dst is nil.
 func (c *Client) Get(dst []byte, url string) (statusCode int, body []byte, err error) {
 	return clientGetURL(dst, url, c)
@@ -223,6 +239,8 @@ func (c *Client) Get(dst []byte, url string) (statusCode int, body []byte, err e
 
 // GetTimeout appends url contents to dst and returns it as body.
 //
+// The function follows redirects. Use Do* for manually handling redirects.
+//
 // New body buffer is allocated if dst is nil.
 //
 // ErrTimeout error is returned if url contents couldn't be fetched
@@ -233,6 +251,8 @@ func (c *Client) GetTimeout(dst []byte, url string, timeout time.Duration) (stat
 
 // GetDeadline appends url contents to dst and returns it as body.
 //
+// The function follows redirects. Use Do* for manually handling redirects.
+//
 // New body buffer is allocated if dst is nil.
 //
 // ErrTimeout error is returned if url contents couldn't be fetched
@@ -245,6 +265,8 @@ func (c *Client) GetDeadline(dst []byte, url string, deadline time.Time) (status
 //
 // Response body is appended to dst, which is returned as body.
 //
+// The function follows redirects. Use Do* for manually handling redirects.
+//
 // New body buffer is allocated if dst is nil.
 //
 // Empty POST body is sent if postArgs is nil.
@@ -263,6 +285,8 @@ func (c *Client) Post(dst []byte, url string, postArgs *Args) (statusCode int, b
 //   - from RequestURI if it contains full url with scheme and host;
 //   - from Host header otherwise.
 //
+// The function doesn't follow redirects. Use Get* for following redirects.
+//
 // Response is ignored if resp is nil.
 //
 // ErrTimeout is returned if the response wasn't returned during
@@ -285,6 +309,8 @@ func (c *Client) DoTimeout(req *Request, resp *Response, timeout time.Duration)
 //   - from RequestURI if it contains full url with scheme and host;
 //   - from Host header otherwise.
 //
+// The function doesn't follow redirects. Use Get* for following redirects.
+//
 // Response is ignored if resp is nil.
 //
 // ErrTimeout is returned if the response wasn't returned until
@@ -301,13 +327,15 @@ func (c *Client) DoDeadline(req *Request, resp *Response, deadline time.Time) er
 // Request must contain at least non-zero RequestURI with full url (including
 // scheme and host) or non-zero Host header + RequestURI.
 //
-// Response is ignored if resp is nil.
-//
 // Client determines the server to be requested in the following order:
 //
 //   - from RequestURI if it contains full url with scheme and host;
 //   - from Host header otherwise.
 //
+// Response is ignored if resp is nil.
+//
+// The function doesn't follow redirects. Use Get* for following redirects.
+//
 // ErrNoFreeConns is returned if all Client.MaxConnsPerHost connections
 // to the requested host are busy.
 //
@@ -561,6 +589,8 @@ func (c *HostClient) LastUseTime() time.Time {
 
 // Get appends url contents to dst and returns it as body.
 //
+// The function follows redirects. Use Do* for manually handling redirects.
+//
 // New body buffer is allocated if dst is nil.
 func (c *HostClient) Get(dst []byte, url string) (statusCode int, body []byte, err error) {
 	return clientGetURL(dst, url, c)
@@ -568,6 +598,8 @@ func (c *HostClient) Get(dst []byte, url string) (statusCode int, body []byte, e
 
 // GetTimeout appends url contents to dst and returns it as body.
 //
+// The function follows redirects. Use Do* for manually handling redirects.
+//
 // New body buffer is allocated if dst is nil.
 //
 // ErrTimeout error is returned if url contents couldn't be fetched
@@ -578,6 +610,8 @@ func (c *HostClient) GetTimeout(dst []byte, url string, timeout time.Duration) (
 
 // GetDeadline appends url contents to dst and returns it as body.
 //
+// The function follows redirects. Use Do* for manually handling redirects.
+//
 // New body buffer is allocated if dst is nil.
 //
 // ErrTimeout error is returned if url contents couldn't be fetched
@@ -590,6 +624,8 @@ func (c *HostClient) GetDeadline(dst []byte, url string, deadline time.Time) (st
 //
 // Response body is appended to dst, which is returned as body.
 //
+// The function follows redirects. Use Do* for manually handling redirects.
+//
 // New body buffer is allocated if dst is nil.
 //
 // Empty POST body is sent if postArgs is nil.
@@ -810,6 +846,8 @@ func ReleaseResponse(resp *Response) {
 // Request must contain at least non-zero RequestURI with full url (including
 // scheme and host) or non-zero Host header + RequestURI.
 //
+// The function doesn't follow redirects. Use Get* for following redirects.
+//
 // Response is ignored if resp is nil.
 //
 // ErrTimeout is returned if the response wasn't returned during
@@ -827,6 +865,8 @@ func (c *HostClient) DoTimeout(req *Request, resp *Response, timeout time.Durati
 // Request must contain at least non-zero RequestURI with full url (including
 // scheme and host) or non-zero Host header + RequestURI.
 //
+// The function doesn't follow redirects. Use Get* for following redirects.
+//
 // Response is ignored if resp is nil.
 //
 // ErrTimeout is returned if the response wasn't returned until
@@ -934,6 +974,8 @@ var errorChPool sync.Pool
 // Request must contain at least non-zero RequestURI with full url (including
 // scheme and host) or non-zero Host header + RequestURI.
 //
+// The function doesn't follow redirects. Use Get* for following redirects.
+//
 // Response is ignored if resp is nil.
 //
 // ErrNoFreeConns is returned if all HostClient.MaxConns connections
@@ -1466,6 +1508,8 @@ type pipelineWork struct {
 // Request must contain at least non-zero RequestURI with full url (including
 // scheme and host) or non-zero Host header + RequestURI.
 //
+// The function doesn't follow redirects. Use Get* for following redirects.
+//
 // Response is ignored if resp is nil.
 //
 // ErrTimeout is returned if the response wasn't returned during
@@ -1483,6 +1527,8 @@ func (c *PipelineClient) DoTimeout(req *Request, resp *Response, timeout time.Du
 // Request must contain at least non-zero RequestURI with full url (including
 // scheme and host) or non-zero Host header + RequestURI.
 //
+// The function doesn't follow redirects. Use Get* for following redirects.
+//
 // Response is ignored if resp is nil.
 //
 // ErrTimeout is returned if the response wasn't returned until
@@ -1542,6 +1588,8 @@ func (c *PipelineClient) DoDeadline(req *Request, resp *Response, deadline time.
 // Request must contain at least non-zero RequestURI with full url (including
 // scheme and host) or non-zero Host header + RequestURI.
 //
+// The function doesn't follow redirects. Use Get* for following redirects.
+//
 // Response is ignored if resp is nil.
 //
 // ErrNoFreeConns is returned if all HostClient.MaxConns connections