encoding/json: documented behavior unmarshaling JSON null into json.Unmarshaler is unclear

[anzdaddy]

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

1.10.1

Does this issue reproduce with the latest release?

Yes

What operating system and processor architecture are you using (go env)?

N/A

What did you do?

I read the documentation for json.Unmarshal and json.Unmarshaler.UnmarshalJSON, and the relevant code:

go/src/encoding/json/decode.go

Lines 482 to 494 in 568d484

	if v.IsNil() {
	v.Set(reflect.New(v.Type().Elem()))
	}
	if v.Type().NumMethod() > 0 {
	if u, ok := v.Interface().(Unmarshaler); ok {
	return u, nil, reflect.Value{}
	}
	if !decodingNull {
	if u, ok := v.Interface().(encoding.TextUnmarshaler); ok {
	return nil, u, reflect.Value{}
	}
	}
	}

What did you expect to see?

A statement to the effect that json.Unmarshal will zero the value before calling json.Unmarshaler.UnmarshalJSON.

What did you see instead?

According to the documentation, json.Unmarshal passes null to json.Unmarshaler.UnmarshalJSON. However, it doesn't explain that, prior to making the call, it sets the field to the zero value.

This is hinted at in the documentation for json.Unmarshaler, wherein it requires treating null inputs as a no-op, but this leaves the reader wondering what state the field is left in if it wasn't already the zero value.

[ianlancetaylor]

But it doesn't set the field to the zero value. Consider:

https://play.golang.org/p/uNoEYH-UAqs

[anzdaddy]

🤦 Sorry, I misread the if.