net/http: fix and normalize the [Server.][ListenAnd]Serve[TLS] docs

The only inaccurate part was the HTTP/2 caveat in Server.ServeTLS, which
only applies to the plain Serve variant.

The restriction implemented in shouldConfigureHTTP2ForServe is not on
the setupHTTP2_ServeTLS codepath because ServeTLS owns the tls.Listener,
so we fix it for the user instead of disabling HTTP/2.

Fixes #24607

Change-Id: Ie5f207d0201f09db27bf81b75535e5f6fdaf91e2
Reviewed-on: https://go-review.googlesource.com/103815
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

1 files changed, 22 insertions, 0 deletions

diff --git a/src/net/http/example_test.go b/src/net/http/example_test.go
index 9de0893e87..53fb0bbb4e 100644
--- a/src/net/http/example_test.go
+++ b/src/net/http/example_test.go
@@ -137,3 +137,25 @@ func ExampleServer_Shutdown() {
 
 	<-idleConnsClosed
 }
+
+func ExampleListenAndServeTLS() {
+	http.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
+		io.WriteString(w, "Hello, TLS!\n")
+	})
+
+	// One can use generate_cert.go in crypto/tls to generate cert.pem and key.pem.
+	log.Printf("About to listen on 8443. Go to https://127.0.0.1:8443/")
+	err := http.ListenAndServeTLS(":8443", "cert.pem", "key.pem", nil)
+	log.Fatal(err)
+}
+
+func ExampleListenAndServe() {
+	// Hello world, the web server
+
+	helloHandler := func(w http.ResponseWriter, req *http.Request) {
+		io.WriteString(w, "Hello, world!\n")
+	}
+
+	http.HandleFunc("/hello", helloHandler)
+	log.Fatal(http.ListenAndServe(":8080", nil))
+}