net/http/httptest: update docs, remove old inaccurate sentence

The "After it is called, changing rw.Header will not affect
rw.HeaderMap" claim predates the Result method which changed how the
Recorder should be used.

Fixes #32144
Fixes #32136

Change-Id: I95bdfa5ac489ce7b0202824bb5663f4da188e8a7
Reviewed-on: https://go-review.googlesource.com/c/go/+/178058
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>

diff --git a/src/net/http/httptest/recorder.go b/src/net/http/httptest/recorder.go
index f2350f0a8d21691bbe31148d6bac6f9b6f0f7c55..d0bc0fade98d91abe87e05d328b4414e49c707b7 100644 (file)
--- a/src/net/http/httptest/recorder.go
+++ b/src/net/http/httptest/recorder.go
@@ -59,7 +59,10 @@ func NewRecorder() *ResponseRecorder {
 // an explicit DefaultRemoteAddr isn't set on ResponseRecorder.
 const DefaultRemoteAddr = "1.2.3.4"
 
-// Header returns the response headers.
+// Header implements http.ResponseWriter. It returns the response
+// headers to mutate within a handler. To test the headers that were
+// written after a handler completes, use the Result method and see
+// the returned Response value's Header.
 func (rw *ResponseRecorder) Header() http.Header {
        m := rw.HeaderMap
        if m == nil {
@@ -98,7 +101,8 @@ func (rw *ResponseRecorder) writeHeader(b []byte, str string) {
        rw.WriteHeader(200)
 }
 
-// Write always succeeds and writes to rw.Body, if not nil.
+// Write implements http.ResponseWriter. The data in buf is written to
+// rw.Body, if not nil.
 func (rw *ResponseRecorder) Write(buf []byte) (int, error) {
        rw.writeHeader(buf, "")
        if rw.Body != nil {
@@ -107,7 +111,8 @@ func (rw *ResponseRecorder) Write(buf []byte) (int, error) {
        return len(buf), nil
 }
 
-// WriteString always succeeds and writes to rw.Body, if not nil.
+// WriteString implements io.StringWriter. The data in str is written
+// to rw.Body, if not nil.
 func (rw *ResponseRecorder) WriteString(str string) (int, error) {
        rw.writeHeader(nil, str)
        if rw.Body != nil {
@@ -116,8 +121,7 @@ func (rw *ResponseRecorder) WriteString(str string) (int, error) {
        return len(str), nil
 }
 
-// WriteHeader sets rw.Code. After it is called, changing rw.Header
-// will not affect rw.HeaderMap.
+// WriteHeader implements http.ResponseWriter.
 func (rw *ResponseRecorder) WriteHeader(code int) {
        if rw.wroteHeader {
                return
@@ -130,7 +134,8 @@ func (rw *ResponseRecorder) WriteHeader(code int) {
        rw.snapHeader = rw.HeaderMap.Clone()
 }
 
-// Flush sets rw.Flushed to true.
+// Flush implements http.Flusher. To test whether Flush was
+// called, see rw.Flushed.
 func (rw *ResponseRecorder) Flush() {
        if !rw.wroteHeader {
                rw.WriteHeader(200)