json.Unmarshal() documentation doesn't make it clear that struct fields need to be exported

[gopherbot]

by timothy.l.jones:

The json.Unmarshal() documentation doesn't make it clear that struct fields need to be
exported for Unmarshal to work correctly. This is only documented at
http://golang.org/doc/articles/json_and_go.html , but perhaps it should also be
documented in the json API.

* What steps will reproduce the problem?
1. visit http://golang.org/pkg/encoding/json/#Unmarshal
2. The documentation says "To unmarshal JSON into a struct, Unmarshal matches
incoming object keys to the keys used by Marshal (either the struct field name or its
tag), preferring an exact match but also accepting a case-insensitive match."
3. This implies that the following would work:

type Blah struct {
  name string
  num float64
}
....
var result Blah
err := json.Unmarshal(blob,&result)
 
See http://play.golang.org/p/P2CWHLa3jt

But instead, the struct needs to be changed to:

type Blah struct {
  Name string   // Note the uppercase field names
  Num float64
}

* What is the expected output?

I would expect that the documentation in http://golang.org/pkg/encoding/json/#Unmarshal
says something like "note that Unmarshal is only able to access exported struct
fields"

What do you see instead?

This information is only available in the article at
http://golang.org/doc/articles/json_and_go.html

Which compiler are you using (5g, 6g, 8g, gccgo)?
N/A

Which operating system are you using?
N/A

Which version are you using?  (run 'go version')
Online doco.

Please provide any additional information below.

[robpike]

Comment 1:

The docs say that Unmarshal uses the same rules as Marshal, and Marshal is clear that
only exported fields are encoded. In other words, it is documented in the JSON API,
despite the claim made in the issue.
Perhaps some of the key points should be reiterated, but the documentation is already
long.

Status changed to WontFix.