go icon indicating copy to clipboard operation
go copied to clipboard

encoding/json/v2: document MarshalJSONTo (etc) method use recommendations

Open prattmic opened this issue 2 months ago • 1 comments

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:

  1. Callers should prefer to use encoding/json/v2.Marshal rather than calling the methods directly, as Marshal will handle the special cases internally.
  2. If callers do call MarshalJSONTo directly, 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

prattmic avatar Dec 05 '25 16:12 prattmic

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).

prattmic avatar Dec 05 '25 16:12 prattmic