net/http: add section headers to package doc
Change-Id: I2379cceeb74cb8511058b24cdd100b21649505ce
Reviewed-on: https://go-review.googlesource.com/c/go/+/462197
Run-TryBot: Russ Cox <rsc@golang.org>
TryBot-Result: Gopher Robot <gobot@golang.org>
Reviewed-by: Damien Neil <dneil@google.com>
diff --git a/src/net/http/doc.go b/src/net/http/doc.go
index 67c4246..d9e6aaf 100644
--- a/src/net/http/doc.go
+++ b/src/net/http/doc.go
@@ -14,7 +14,7 @@
resp, err := http.PostForm("http://example.com/form",
url.Values{"key": {"Value"}, "id": {"123"}})
-The client must close the response body when finished with it:
+The caller must close the response body when finished with it:
resp, err := http.Get("http://example.com/")
if err != nil {
@@ -24,6 +24,8 @@
body, err := io.ReadAll(resp.Body)
// ...
+# Clients and Transports
+
For control over HTTP client headers, redirect policy, and other
settings, create a Client:
@@ -54,6 +56,8 @@
Clients and Transports are safe for concurrent use by multiple
goroutines and for efficiency should only be created once and re-used.
+# Servers
+
ListenAndServe starts an HTTP server with a given address and handler.
The handler is usually nil, which means to use DefaultServeMux.
Handle and HandleFunc add handlers to DefaultServeMux:
@@ -78,11 +82,13 @@
}
log.Fatal(s.ListenAndServe())
+# 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 environment variables are
+map. Alternatively, the following GODEBUG settings are
currently supported:
GODEBUG=http2client=0 # disable HTTP/2 client support
@@ -90,9 +96,7 @@
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. Please report any issues before disabling HTTP/2
-support: https://golang.org/s/http2bug
+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