x/website, x/pkgsite: net/http.ServeMux.Handle example reads poorly if shown as a complete program

[readpe]

What version of Go are you using (go version)?

$ go version
go version go1.14.4 darwin/amd64

Does this issue reproduce with the latest release?

In current package documentation at https://golang.org/pkg/net/http/#example_ServeMux_Handle

What operating system and processor architecture are you using (go env)?

go env Output

$ go env
GOARCH="amd64"
GOOS="darwin"

What did you expect to see?

Expected example to initiate http.ListenAndServe or equivalent with new ServeMux

package main

import (
	"fmt"
	"log"
	"net/http"
)

type apiHandler struct{}

func (apiHandler) ServeHTTP(http.ResponseWriter, *http.Request) {}

func main() {
	mux := http.NewServeMux()
	mux.Handle("/api/", apiHandler{})
	mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
		// The "/" pattern matches everything, so we need to check
		// that we're at the root here.
		if req.URL.Path != "/" {
			http.NotFound(w, req)
			return
		}
		fmt.Fprintf(w, "Welcome to the home page!")
	})
	log.Fatal(http.ListenAndServe(":8080", mux))
}

What did you see instead?

The example immediately exits without serving

package main

import (
	"fmt"
	"net/http"
)

type apiHandler struct{}

func (apiHandler) ServeHTTP(http.ResponseWriter, *http.Request) {}

func main() {
	mux := http.NewServeMux()
	mux.Handle("/api/", apiHandler{})
	mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
		// The "/" pattern matches everything, so we need to check
		// that we're at the root here.
		if req.URL.Path != "/" {
			http.NotFound(w, req)
			return
		}
		fmt.Fprintf(w, "Welcome to the home page!")
	})
}

I'd be happy to work on this for my first contribution if accepted

[dmitshur]

Thanks for reporting. I agree the example, as displayed at https://golang.org/pkg/net/http/#example_ServeMux_Handle, can feel like it's missing some code to start the server.

However, the example as written in code (see here), and displayed on https://pkg.go.dev/net/http@go1.14.4#example-ServeMux.Handle at this time seems a lot more reasonable to omit starting up a server, since it's meant to show how to use the ServeMux.Handle method:

mux := http.NewServeMux()
mux.Handle("/api/", apiHandler{})
mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
	// The "/" pattern matches everything, so we need to check
	// that we're at the root here.
	if req.URL.Path != "/" {
		http.NotFound(w, req)
		return
	}
	fmt.Fprintf(w, "Welcome to the home page!")
})

So, we should decide whether to do given it's displayed differently on those websites, and take it into account if examples are displayed differently in the future.

Given that the example doesn't have an // Output: comment, it doesn't seem like it should be displayed as a complete program, so the current pkg.go.dev (and godoc.org, see https://godoc.org/net/http#example-ServeMux-Handle) version seems better.

/cc @julieqiu @jba @shaqque