net/http: bit more docs on Client vs Transport

This isn't as bad as it used to be, but add a bit
more detail to close the issue.

Fixes #3359

R=golang-dev, adg
CC=golang-dev
https://golang.org/cl/7606044

diff --git a/src/pkg/net/http/client.go b/src/pkg/net/http/client.go
index 5ee0804c7da9fc2d3fc4db76d91e28d8688df565..a34d47be1fa7ed142f073ad1952d2c93189505aa 100644 (file)
--- a/src/pkg/net/http/client.go
+++ b/src/pkg/net/http/client.go
@@ -19,12 +19,16 @@ import (
        "strings"
 )
 
-// A Client is an HTTP client. Its zero value (DefaultClient) is a usable client
-// that uses DefaultTransport.
+// A Client is an HTTP client. Its zero value (DefaultClient) is a
+// usable client that uses DefaultTransport.
 //
-// The Client's Transport typically has internal state (cached
-// TCP connections), so Clients should be reused instead of created as
+// The Client's Transport typically has internal state (cached TCP
+// connections), so Clients should be reused instead of created as
 // needed. Clients are safe for concurrent use by multiple goroutines.
+//
+// A Client is higher-level than a RoundTripper (such as Transport)
+// and additionally handles HTTP details such as cookies and
+// redirects.
 type Client struct {
        // Transport specifies the mechanism by which individual
        // HTTP requests are made.

diff --git a/src/pkg/net/http/response.go b/src/pkg/net/http/response.go
index 391ebbf6d70f6337605d914eb3504791fc5852d2..9a7e4e319b09a0db296293b73b2931231fb34cce 100644 (file)
--- a/src/pkg/net/http/response.go
+++ b/src/pkg/net/http/response.go
@@ -46,6 +46,9 @@ type Response struct {
        // The http Client and Transport guarantee that Body is always
        // non-nil, even on responses without a body or responses with
        // a zero-lengthed body.
+       //
+       // The Body is automatically dechunked if the server replied
+       // with a "chunked" Transfer-Encoding.
        Body io.ReadCloser
 
        // ContentLength records the length of the associated content.  The

diff --git a/src/pkg/net/http/transport.go b/src/pkg/net/http/transport.go
index f1c6fb2dcb75ebc0a38f860a0664e6afc56f838a..08ced2c3d1a9e3302669173623caa0ce8110d6e2 100644 (file)
--- a/src/pkg/net/http/transport.go
+++ b/src/pkg/net/http/transport.go
@@ -49,10 +49,6 @@ type Transport struct {
        altMu      sync.RWMutex
        altProto   map[string]RoundTripper // nil or map of URI scheme => RoundTripper
 
-       // TODO: tunable on global max cached connections
-       // TODO: tunable on timeout on cached connections
-       // TODO: optional pipelining
-
        // Proxy specifies a function to return a proxy for a given
        // Request. If the function returns a non-nil error, the
        // request is aborted with the provided error.
@@ -68,7 +64,18 @@ type Transport struct {
        // tls.Client. If nil, the default configuration is used.
        TLSClientConfig *tls.Config
 
-       DisableKeepAlives  bool
+       // DisableKeepAlives, if true, prevents re-use of TCP connections
+       // between different HTTP requests.
+       DisableKeepAlives bool
+
+       // DisableCompression, if true, prevents the Transport from
+       // requesting compression with an "Accept-Encoding: gzip"
+       // request header when the Request contains no existing
+       // Accept-Encoding value. If the Transport requests gzip on
+       // its own and gets a gzipped response, it's transparently
+       // decoded in the Response.Body. However, if the user
+       // explicitly requested gzip it is not automatically
+       // uncompressed.
        DisableCompression bool
 
        // MaxIdleConnsPerHost, if non-zero, controls the maximum idle
@@ -81,6 +88,9 @@ type Transport struct {
        // writing the request (including its body, if any). This
        // time does not include the time to read the response body.
        ResponseHeaderTimeout time.Duration
+
+       // TODO: tunable on global max cached connections
+       // TODO: tunable on timeout on cached connections
 }
 
 // ProxyFromEnvironment returns the URL of the proxy to use for a
@@ -133,6 +143,9 @@ func (tr *transportRequest) extraHeaders() Header {
 }
 
 // RoundTrip implements the RoundTripper interface.
+//
+// For higher-level HTTP client support (such as handling of cookies
+// and redirects), see Get, Post, and the Client type.
 func (t *Transport) RoundTrip(req *Request) (resp *Response, err error) {
        if req.URL == nil {
                return nil, errors.New("http: nil Request.URL")