encoding/json: add example for Indent, clarify the docs.

There was confusion in the behavior of json.Indent; This change
attempts to clarify the behavior by providing a bit more verbiage
to the documentation as well as provide an example function.

Fixes #7821.

LGTM=robert.hencke, adg
R=golang-codereviews, minux.ma, bradfitz, aram, robert.hencke, r, adg
CC=golang-codereviews
https://golang.org/cl/97840044

diff --git a/src/pkg/encoding/json/example_test.go b/src/pkg/encoding/json/example_test.go
index ea0bc149c36dacd7c3487d0b3cd37a0359c68a85..ca4e5ae68d4a395103b665cd8fbdc345a1c82f40 100644 (file)
--- a/src/pkg/encoding/json/example_test.go
+++ b/src/pkg/encoding/json/example_test.go
@@ -5,6 +5,7 @@
 package json_test
 
 import (
+       "bytes"
        "encoding/json"
        "fmt"
        "io"
@@ -127,3 +128,34 @@ func ExampleRawMessage() {
        // YCbCr &{255 0 -10}
        // RGB &{98 218 255}
 }
+
+func ExampleIndent() {
+       type Road struct {
+               Name   string
+               Number int
+       }
+       roads := []Road{
+               {"Diamond Fork", 29},
+               {"Sheep Creek", 51},
+       }
+
+       b, err := json.Marshal(roads)
+       if err != nil {
+               log.Fatal(err)
+       }
+
+       var out bytes.Buffer
+       json.Indent(&out, b, "=", "\t")
+       out.WriteTo(os.Stdout)
+       // Output:
+       // [
+       // =    {
+       // =            "Name": "Diamond Fork",
+       // =            "Number": 29
+       // =    },
+       // =    {
+       // =            "Name": "Sheep Creek",
+       // =            "Number": 51
+       // =    }
+       // =]
+}

diff --git a/src/pkg/encoding/json/indent.go b/src/pkg/encoding/json/indent.go
index 11ef709cce7ce9478c1cfef733c4f59c3978ac6a..e1bacafd6b860e2e2d5bbf081b4bbd41b09ebcf4 100644 (file)
--- a/src/pkg/encoding/json/indent.go
+++ b/src/pkg/encoding/json/indent.go
@@ -69,8 +69,9 @@ func newline(dst *bytes.Buffer, prefix, indent string, depth int) {
 // Each element in a JSON object or array begins on a new,
 // indented line beginning with prefix followed by one or more
 // copies of indent according to the indentation nesting.
-// The data appended to dst has no trailing newline, to make it easier
-// to embed inside other formatted JSON data.
+// The data appended to dst does not begin with the prefix nor
+// any indentation, and has no trailing newline, to make it
+// easier to embed inside other formatted JSON data.
 func Indent(dst *bytes.Buffer, src []byte, prefix, indent string) error {
        origLen := dst.Len()
        var scan scanner