From 88f9ab8926dc3bbd55ab37e053a780985a75e472 Mon Sep 17 00:00:00 2001 From: Rob Pike Date: Thu, 11 Apr 2013 12:46:23 -0700 Subject: [PATCH] encoding/json: documentation regarding anonymous fields. R=golang-dev, iant CC=golang-dev https://golang.org/cl/8545046 --- src/pkg/encoding/json/encode.go | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/src/pkg/encoding/json/encode.go b/src/pkg/encoding/json/encode.go index b07dbd1aca..fd4239c163 100644 --- a/src/pkg/encoding/json/encode.go +++ b/src/pkg/encoding/json/encode.go @@ -3,7 +3,8 @@ // license that can be found in the LICENSE file. // Package json implements encoding and decoding of JSON objects as defined in -// RFC 4627. +// RFC 4627. The mapping between JSON objects and Go values is described +// in the documentation for the Marshal and Unmarshal functions. // // See "JSON and Go" for an introduction to this package: // http://golang.org/doc/articles/json_and_go.html @@ -86,9 +87,21 @@ import ( // underscores and slashes. // // Anonymous struct fields are usually marshaled as if their inner exported fields -// were fields in the outer struct, subject to the usual Go visibility rules. +// were fields in the outer struct, subject to the usual Go visibility rules amended +// as described in the next paragraph. // An anonymous struct field with a name given in its JSON tag is treated as -// having that name instead of as anonymous. +// having that name, rather than being anonymous. +// +// The Go visibility rules for struct fields are amended for JSON when +// deciding which field to marshal or unmarshal. If there are +// multiple fields at the same level, and that level is the least +// nested (and would therefore be the nesting level selected by the +// usual Go rules), the following extra rules apply: +// +// 1) Of those fields, if any are JSON-tagged, only tagged fields are considered, +// even if there are multiple untagged fields that would otherwise conflict. +// 2) If there is exactly one field (tagged or not according to the first rule), that is selected. +// 3) Otherwise there are multiple fields, and all are ignored; no error occurs. // // Handling of anonymous struct fields is new in Go 1.1. // Prior to Go 1.1, anonymous struct fields were ignored. To force ignoring of -- 2.50.0