(This is a continuation of #25763 and #16717.)

The httptest.ResponseRecorder.HeaderMap struct field was deprecated in CL 117675, with the deprecation notice pointing users to the Response.Header map as returned by the Result method. This was to resolve issue #25763 (which provides rationale for why that was done).

However, there's also a ResponseRecorder.Header method which does little more than provide direct access to the HeaderMap field (it also initializes the map if it's nil):

// Header returns the response headers.
func (rw *ResponseRecorder) Header() http.Header {
	m := rw.HeaderMap
	if m == nil {
		m = make(http.Header)
		rw.HeaderMap = m
	}
	return m
}

This puts users in an awkward position. If they read the deprecation notice on the HeaderMap field (and understand the rationale for why it was deprecated by reading through issue #25763), and also know the internal implementation details of the Header method, they'll know that they shouldn't be using the Header method either.

If they don't know the internal implementation details of the Header method, they won't know how it differs from the Response.Header map as returned by the Result method and how to decide which one to use.

Users shouldn't have to read the internal implementation of methods and make these kind of deductions. If the HeaderMap field is deprecated, the current Header method should be too:

-// Header returns the response headers.
+// Header returns the response headers explicitly set by the Handler.
+// It is an internal detail.
+//
+// Deprecated: Header exists for historical compatibility
+// and should not be used. To access the headers returned by a handler,
+// use the Response.Header map as returned by the Result method.
 func (rw *ResponseRecorder) Header() http.Header {

/cc @cespare @bradfitz @dominikh