pkg: a slew of examples

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

src/pkg/encoding/json/example_test.go

@@ -7,7 +7,10 @@ package json_test
 import (
 	"encoding/json"
 	"fmt"
+	"io"
+	"log"
 	"os"
+	"strings"
 )
 
 func ExampleMarshal() {
@@ -48,3 +51,33 @@ func ExampleUnmarshal() {
 	// Output:
 	// [{Name:Platypus Order:Monotremata} {Name:Quoll Order:Dasyuromorphia}]
 }
+
+// This example uses a Decoder to decode a stream of distinct JSON values.
+func ExampleDecoder() {
+	const jsonStream = `
+		{"Name": "Ed", "Text": "Knock knock."}
+		{"Name": "Sam", "Text": "Who's there?"}
+		{"Name": "Ed", "Text": "Go fmt."}
+		{"Name": "Sam", "Text": "Go fmt who?"}
+		{"Name": "Ed", "Text": "Go fmt yourself!"}
+	`
+	type Message struct {
+		Name, Text string
+	}
+	dec := json.NewDecoder(strings.NewReader(jsonStream))
+	for {
+		var m Message
+		if err := dec.Decode(&m); err == io.EOF {
+			break
+		} else if err != nil {
+			log.Fatal(err)
+		}
+		fmt.Printf("%s: %s\n", m.Name, m.Text)
+	}
+	// Output:
+	// Ed: Knock knock.
+	// Sam: Who's there?
+	// Ed: Go fmt.
+	// Sam: Go fmt who?
+	// Ed: Go fmt yourself!
+}