net/http/httptest: Better document usage of ResponseRecorder.HeaderMap vs. ResponseRecorder.Result

[cespare]

The Go 1.7 release notes say:

The ResponseRecorder's new Result method returns the recorded http.Response. Tests that need to check the response's headers or trailers should call Result and inspect the response fields instead of accessing ResponseRecorder's HeaderMap directly.

However, the documentation itself doesn't give much guidance. The closest it says is

The Response.Header is a snapshot of the headers at the time of the first write call, or at the time of this call, if the handler never did a write.

If I were just reading the httptest docs, I would probably just use HeaderMap as it's more convenient. It would be good to put a caveat by the definition of HeaderMap.

[cespare]

/cc @bradfitz

[gopherbot]

CL https://golang.org/cl/32190 mentions this issue.