encoding/json: clarify Unmarshal behavior for string keys that implement encoding.TextUnmarshaler

[Oncilla]

What version of Go are you using (go version)?

$ go version
go version go1.11.9 linux/amd64

Does this issue reproduce with the latest release?

yes

What did you do?

https://play.golang.org/p/keu0ix2OtsZ

What did you expect to see?

I expected json.Unmarshal to always use the UnmarshalText method on all key types.

The documentation is not very clear about this:
(from https://tip.golang.org/pkg/encoding/json/#Unmarshal)

To unmarshal a JSON object into a map, Unmarshal first establishes a map to use. If the map is nil, Unmarshal allocates a new map. Otherwise Unmarshal reuses the existing map, keeping existing entries. Unmarshal then stores key-value pairs from the JSON object into the map. The map's key type must either be a string, an integer, or implement encoding.TextUnmarshaler.

From that description, I would expect json.Unmarshal to use UnmarshalText on string types that implement encoding.TextUnmarshaler.
Also, I would expect it to call UnmarshalText and not UnmarshalJSON on int keys that implement json.Unmarshler.

I gather from the related issue #28827 that this cannot be changed for compatibility reasons.
Thus, the documentation should be more explicit what the expected outcome is.

What did you see instead?

When unmarshalling string types that implement the encoding.TextUnmarshaler, json.Unmarshal does not call the UnmarshalText method.

Also, json.Unmarshal happily uses UnmarshalJSON on int keys

[FiloSottile]

We'd probably take CLs to make the docs clearer, both here and in #28827.

[eliben]

I sent https://golang.org/cl/188417 to fix #28827

If that seems reasonable, I can send a fix for this one too

[eliben]

Looking at the code implementing this in json/decode.go, it seems like the usage of UnmarshalJSON for types that aren't string types has been there from very early on. 7e88674 added support for encoding.TextUnmarshaler and the check for json.Unmarshaler was already there.

I'll send a CL to clarify this behavior in the documentation

[gopherbot]

Change https://golang.org/cl/188821 mentions this issue: encoding/json: clarify Unmarshal behavior for map keys