encoding/json: Unmarshal to nil pointer documentation discrepancy

[JovanCe]

When trying to unmarshal a json string into a nil pointer, the operation fails as can be seen here:
https://play.golang.org/p/wL6UDpaJ-h

The error returned is InvalidUnmarshalError whose docs clearly state:
"The argument to Unmarshal must be a non-nil pointer." (https://golang.org/pkg/encoding/json/#InvalidUnmarshalError)

But the docs for the Unmarshal function state:
"Unmarshal unmarshals the JSON into the value pointed at by the pointer. If the pointer is nil, Unmarshal allocates a new value for it to point to."
(https://golang.org/pkg/encoding/json/#Unmarshal)

Obviously, the behaviour implemented is the one from the error docs.

Curiously, this works:
https://play.golang.org/p/w-Sg24qcCo
So, a reference to a nil pointer is accepted but the nil pointer itself is not. Anyone care to clarify?

go1.7.4 darwin/amd64

[shantuo]

My understanding is that this is a documentation bug. The behavior of returning an InvalidUnmarshalError looks work-as-intended. I guess the docs for the Unmarshal function means "If the pointer points to nil"? Because Unmarshal cannot modify the passed nil pointer.

[gopherbot]

CL https://golang.org/cl/36478 mentions this issue.