encoding/json: document buffering

Fixes #1955.

R=golang-dev, gri
CC=golang-dev
https://golang.org/cl/5643058

src/pkg/encoding/json/stream.go

@@ -19,6 +19,9 @@ type Decoder struct {
 }
 
 // NewDecoder returns a new decoder that reads from r.
+//
+// The decoder introduces its own buffering and may
+// read data from r beyond the JSON values requested.
 func NewDecoder(r io.Reader) *Decoder {
 	return &Decoder{r: r}
 }