encoding/json: document and test overwrite of slice, map during Unmarshal

Fixes #8837.

Change-Id: Iaaecbb0b324004cb74b16b764126b01315e6a16e
Reviewed-on: https://go-review.googlesource.com/12209
Reviewed-by: Andrew Gerrand <adg@golang.org>

src/encoding/json/decode.go

@@ -48,6 +48,13 @@ import (
 //	map[string]interface{}, for JSON objects
 //	nil for JSON null
 //
+// To unmarshal a JSON array into a slice, Unmarshal resets the slice to nil
+// and then appends each element to the slice.
+//
+// To unmarshal a JSON object into a map, Unmarshal replaces the map
+// with an empty map and then adds key-value pairs from the object to
+// the map.
+//
 // If a JSON value is not appropriate for a given target type,
 // or if a JSON number overflows the target type, Unmarshal
 // skips that field and completes the unmarshalling as best it can.

src/encoding/json/decode_test.go

@@ -217,6 +217,9 @@ type XYZ struct {
 	Z interface{}
 }
 
+func sliceAddr(x []int) *[]int                 { return &x }
+func mapAddr(x map[string]int) *map[string]int { return &x }
+
 var unmarshalTests = []unmarshalTest{
 	// basic types
 	{in: `true`, ptr: new(bool), out: true},
@@ -303,6 +306,12 @@ var unmarshalTests = []unmarshalTest{
 	{in: `["X"]`, ptr: &umslicepT, out: &umsliceT},
 	{in: `{"M":"X"}`, ptr: &umstructT, out: umstructT},
 
+	// Overwriting of data.
+	// This is different from package xml, but it's what we've always done.
+	// Now documented and tested.
+	{in: `[2]`, ptr: sliceAddr([]int{1}), out: []int{2}},
+	{in: `{"key": 2}`, ptr: mapAddr(map[string]int{"old": 0, "key": 1}), out: map[string]int{"key": 2}},
+
 	{
 		in: `{
 			"Level0": 1,