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>

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)