I frequently see code where an http.Response.Body is decoded with json.Decoder, under the presumption that json.Decoder performs memory saving streaming. In fact, it is not more efficient and it is arguably incorrect for http.Responses where only one value should be present.

Here is the current docstring:

A Decoder reads and decodes JSON values from an input stream.

Here is a proposed docstring:

A Decoder reads and decodes JSON values from an input stream. For a stream that should only have a single JSON value, use Unmarshal.