net/http: document relation and interaction with golang.org/x/net/http2

Fixes #16412

Change-Id: Idc65d2a62414a9b1573e6bd9f8601b52985b5dea
Reviewed-on: https://go-review.googlesource.com/33110
Reviewed-by: Ian Lance Taylor <iant@golang.org>

diff --git a/src/net/http/doc.go b/src/net/http/doc.go
index 430aca59062752138452e5279a98d37bdd5f17a9..7855feaaa99f56b64f8fa27aedfc5f13bd292a15 100644 (file)
--- a/src/net/http/doc.go
+++ b/src/net/http/doc.go
@@ -78,19 +78,30 @@ custom Server:
        }
        log.Fatal(s.ListenAndServe())
 
-The http package has transparent support for the HTTP/2 protocol when
-using HTTPS. Programs that must disable HTTP/2 can do so by setting
-Transport.TLSNextProto (for clients) or Server.TLSNextProto (for
-servers) to a non-nil, empty map. Alternatively, the following GODEBUG
-environment variables are currently supported:
+Starting with Go 1.6, the http package has transparent support for the
+HTTP/2 protocol when using HTTPS. Programs that must disable HTTP/2
+can do so by setting Transport.TLSNextProto (for clients) or
+Server.TLSNextProto (for servers) to a non-nil, empty
+map. Alternatively, the following GODEBUG environment variables are
+currently supported:
 
        GODEBUG=http2client=0  # disable HTTP/2 client support
        GODEBUG=http2server=0  # disable HTTP/2 server support
        GODEBUG=http2debug=1   # enable verbose HTTP/2 debug logs
        GODEBUG=http2debug=2   # ... even more verbose, with frame dumps
 
-The GODEBUG variables are not covered by Go's API compatibility promise.
-HTTP/2 support was added in Go 1.6. Please report any issues instead of
-disabling HTTP/2 support: https://golang.org/s/http2bug
+The GODEBUG variables are not covered by Go's API compatibility
+promise. Please report any issues before disabling HTTP/2
+support: https://golang.org/s/http2bug
+
+The http package's Transport and Server both automatically enable
+HTTP/2 support for simple configurations. To enable HTTP/2 for more
+complex configurations, to use lower-level HTTP/2 features, or to use
+a newer version of Go's http2 package, import "golang.org/x/net/http2"
+directly and use its ConfigureTransport and/or ConfigureServer
+functions. Manually configuring HTTP/2 via the golang.org/x/net/http2
+package takes precedence over the net/http package's built-in HTTP/2
+support.
+
 */
 package http