net/http: clarify ServeMux.Handler behavior

Explain that ServeMux.Handler doesn't populate the request with
matches.

Fixes #69623.

Change-Id: If625b3f8e8f4e54b05e1d9a86e8c471045e77763
Reviewed-on: https://go-review.googlesource.com/c/go/+/674095
Reviewed-by: Damien Neil <dneil@google.com>
Reviewed-by: Chressie Himpel <chressie@google.com>
Reviewed-by: Sean Liao <sean@liao.dev>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

diff --git a/src/net/http/server.go b/src/net/http/server.go
index 921b42b59e1659cc32b405d4edd157a8350a472b..ca7383f5e6f6ad018092f2cb6206462c25da1825 100644 (file)
--- a/src/net/http/server.go
+++ b/src/net/http/server.go
@@ -836,6 +836,7 @@ var copyBufPool = sync.Pool{New: func() any { return new([copyBufPoolSize]byte)
 func getCopyBuf() []byte {
        return copyBufPool.Get().(*[copyBufPoolSize]byte)[:]
 }
+
 func putCopyBuf(b []byte) {
        if len(b) != copyBufPoolSize {
                panic("trying to put back buffer of the wrong size in the copyBufPool")
@@ -2674,6 +2675,10 @@ func stripHostPort(h string) string {
 //
 // If there is no registered handler that applies to the request,
 // Handler returns a “page not found” handler and an empty pattern.
+//
+// Handler does not modify its argument. In particular, it does not
+// populate named path wildcards, so r.PathValue will always return
+// the empty string.
 func (mux *ServeMux) Handler(r *Request) (h Handler, pattern string) {
        if use121 {
                return mux.mux121.findHandler(r)