net/http: document Request.Header and Request.Close more

Updates #14227

Change-Id: If39f11471ecd307c9483f64e73f9c89fe906ae71
Reviewed-on: https://go-review.googlesource.com/19222
Reviewed-by: Andrew Gerrand <adg@golang.org>
Reviewed-by: Russ Cox <rsc@golang.org>

diff --git a/src/net/http/request.go b/src/net/http/request.go
index 16c5bb43ac4d4c7b7974dfa0c6e1c50c0c28eef3..03f3e2b9747cf2cd5feeb15d6c75cfb50b2bfa11 100644 (file)
--- a/src/net/http/request.go
+++ b/src/net/http/request.go
@@ -99,30 +99,37 @@ type Request struct {
        ProtoMajor int    // 1
        ProtoMinor int    // 0
 
-       // A header maps request lines to their values.
-       // If the header says
+       // Header contains the request header fields either received
+       // by the server or to be sent by the client.
        //
+       // If a server received a request with header lines,
+       //
+       //      Host: example.com
        //      accept-encoding: gzip, deflate
        //      Accept-Language: en-us
-       //      Connection: keep-alive
+       //      fOO: Bar
+       //      foo: two
        //
        // then
        //
        //      Header = map[string][]string{
        //              "Accept-Encoding": {"gzip, deflate"},
        //              "Accept-Language": {"en-us"},
-       //              "Connection": {"keep-alive"},
+       //              "Foo": {"Bar", "two"},
        //      }
        //
-       // HTTP defines that header names are case-insensitive.
-       // The request parser implements this by canonicalizing the
-       // name, making the first character and any characters
-       // following a hyphen uppercase and the rest lowercase.
+       // For incoming requests, the Host header is promoted to the
+       // Request.Host field and removed from the Header map.
        //
-       // For client requests certain headers are automatically
-       // added and may override values in Header.
+       // HTTP defines that header names are case-insensitive. The
+       // request parser implements this by using CanonicalHeaderKey,
+       // making the first character and any characters following a
+       // hyphen uppercase and the rest lowercase.
        //
-       // See the documentation for the Request.Write method.
+       // For client requests, certain headers such as Content-Length
+       // and Connection are automatically written when needed and
+       // values in Header may be ignored. See the documentation
+       // for the Request.Write method.
        Header Header
 
        // Body is the request's body.
@@ -152,8 +159,15 @@ type Request struct {
        TransferEncoding []string
 
        // Close indicates whether to close the connection after
-       // replying to this request (for servers) or after sending
-       // the request (for clients).
+       // replying to this request (for servers) or after sending this
+       // request and reading its response (for clients).
+       //
+       // For server requests, the HTTP server handles this automatically
+       // and this field is not needed by Handlers.
+       //
+       // The client requests, setting this field prevents re-use of
+       // TCP connections between requests to the same hosts, as if
+       // Transport.DisableKeepAlives were set.
        Close bool
 
        // For server requests Host specifies the host on which the