net/http: update HTTP/2 documentation to reference new config features

Update the package docs to point users at the modern HTTP/2
configuration APIs.

Mention in the TLSNextProto documentation that this field is
superseded by the Protocols field for most user-facing purposes.

Change-Id: I30cd9a85a27e1174338f0d6b887f98c28eac5b5d
Reviewed-on: https://go-review.googlesource.com/c/go/+/709797
Reviewed-by: Nicholas Husin <nsh@golang.org>
Reviewed-by: Nicholas Husin <husin@google.com>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

3 files changed, 21 insertions, 22 deletions

diff --git a/src/net/http/doc.go b/src/net/http/doc.go
index f7ad3ae762..24e07352ca 100644
--- a/src/net/http/doc.go
+++ b/src/net/http/doc.go
@@ -84,27 +84,26 @@ custom Server:
 
 # HTTP/2
 
-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 settings are
-currently supported:
+The http package has transparent support for the HTTP/2 protocol.
+
+[Server] and [DefaultTransport] automatically enable HTTP/2 support
+when using HTTPS. [Transport] does not enable HTTP/2 by default.
+
+To enable or disable support for HTTP/1, HTTP/2, and/or unencrypted HTTP/2,
+see the [Server.Protocols] and [Transport.Protocols] configuration fields.
+
+To configure advanced HTTP/2 features, see the [Server.HTTP2] and
+[Transport.HTTP2] configuration fields.
+
+Alternatively, the following GODEBUG settings 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
 
-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.
+The "omithttp2" build tag may be used to disable the HTTP/2 implementation
+contained in the http package.
 */
+
 package http
diff --git a/src/net/http/server.go b/src/net/http/server.go
index 4078c89906..02554d1a20 100644
--- a/src/net/http/server.go
+++ b/src/net/http/server.go
@@ -3066,6 +3066,9 @@ type Server struct {
 	// automatically closed when the function returns.
 	// If TLSNextProto is not nil, HTTP/2 support is not enabled
 	// automatically.
+	//
+	// Historically, TLSNextProto was used to disable HTTP/2 support.
+	// The Server.Protocols field now provides a simpler way to do this.
 	TLSNextProto map[string]func(*Server, *tls.Conn, Handler)
 
 	// ConnState specifies an optional callback function that is
@@ -3094,9 +3097,6 @@ type Server struct {
 	ConnContext func(ctx context.Context, c net.Conn) context.Context
 
 	// HTTP2 configures HTTP/2 connections.
-	//
-	// This field does not yet have any effect.
-	// See https://go.dev/issue/67813.
 	HTTP2 *HTTP2Config
 
 	// Protocols is the set of protocols accepted by the server.
diff --git a/src/net/http/transport.go b/src/net/http/transport.go
index 5cef9be487..a560765d33 100644
--- a/src/net/http/transport.go
+++ b/src/net/http/transport.go
@@ -249,6 +249,9 @@ type Transport struct {
 	// must return a RoundTripper that then handles the request.
 	// If TLSNextProto is not nil, HTTP/2 support is not enabled
 	// automatically.
+	//
+	// Historically, TLSNextProto was used to disable HTTP/2 support.
+	// The Transport.Protocols field now provides a simpler way to do this.
 	TLSNextProto map[string]func(authority string, c *tls.Conn) RoundTripper
 
 	// ProxyConnectHeader optionally specifies headers to send to
@@ -296,9 +299,6 @@ type Transport struct {
 	ForceAttemptHTTP2 bool
 
 	// HTTP2 configures HTTP/2 connections.
-	//
-	// This field does not yet have any effect.
-	// See https://go.dev/issue/67813.
 	HTTP2 *HTTP2Config
 
 	// Protocols is the set of protocols supported by the transport.