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 67c4246c6080f6340c64df01fcce04baf8ef6f59..d9e6aafb4e326a858c6738360b962c6cfdab1cb6 100644 (file)
--- a/src/net/http/doc.go
+++ b/src/net/http/doc.go
@@ -14,7 +14,7 @@ Get, Head, Post, and PostForm make HTTP (or HTTPS) requests:
        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 @@ The client must close the response body when finished with it:
        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 @@ compression, and other settings, create a Transport:
 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 @@ custom Server:
        }
        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 @@ currently supported:
        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