go
go copied to clipboard
encoding/json/v2: document MarshalJSONTo (etc) method use recommendations
For #74322, we decided that that proposal could be decided after the main encoding/json/v2 proposal is complete provided that the various MarshalJSONTo, etc methods document:
- Callers should prefer to use
encoding/json/v2.Marshalrather than calling the methods directly, asMarshalwill handle the special cases internally. - If callers do call
MarshalJSONTodirectly, there is a set of sentinel errors the method may return which they are responsible for handling.
I'm filing this issue to track adding this documentation, as #74322 is now marked post-proposal.
cc @dsnet @neild @ChrisHines
If callers do call MarshalJSONTo directly, there is a set of sentinel errors the method may return which they are responsible for handling.
FWIW, on second thought, even if we add this documentation, wouldn't adding new sentinel errors later be a backwards-incompatible change? Callers that are correct in Go 1.N may no longer be correct in Go 1.(N+1).