New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

encoding/xml, encoding/json: package docs don't mention encoding.TextMarshaler and encoding.TextUnmarshaler #6859

songgao opened this Issue Dec 1, 2013 · 6 comments


None yet
9 participants

songgao commented Dec 1, 2013

version: Go 1.2

What is the expected output?
`encoding/xml` and `encoding/json` should document the behavior that it will check
encoding.TextMarshaler and encoding.TextUnmarshaler.

This comment has been minimized.


dsymonds commented Dec 2, 2013

Comment 1:

Labels changed: added priority-soon, documentation, size-s, removed priority-triage.

Owner changed to @rsc.

Status changed to Accepted.


This comment has been minimized.


rsc commented Dec 4, 2013

Comment 2:

Labels changed: added release-none, removed go1.3maybe.


This comment has been minimized.


rsc commented Dec 4, 2013

Comment 3:

Labels changed: added repo-main.

@rsc rsc added this to the Unplanned milestone Apr 10, 2015

@rsc rsc removed priority-soon labels Apr 10, 2015


This comment has been minimized.


AlekSi commented Jul 6, 2015

I wanted some text format for for my struct so I implemented TextMarshaler and TextUnmarshaler like this:

func (t *T) MarshalText() ([]byte, error) {
    return xml.MarshalIndent(m, "", "  ")

func (t *T) UnmarshalText(b []byte) error {
    return xml.Unmarshal(b, m)

Then I spent an hour debugging why simplest code like t.UnmarshalText(bytes) fails with io.EOF.

Please document this behaviour.

@ALTree ALTree modified the milestones: Go1.10, Unplanned Jul 25, 2017

@ALTree ALTree added the NeedsFix label Jul 25, 2017


This comment has been minimized.

gopherbot commented Nov 7, 2017

Change mentions this issue: encoding/xml,encoding/json: docs and examples using custom marshalers


This comment has been minimized.


leighmcculloch commented Nov 7, 2017

CL 76350 contains:

  • Examples for both encoding/json and encoding/xml that demonstrate using the encoding.TextMarshaler and encoding.TextUnmarshaler interfaces.
  • An example for encoding/xml that demonstrates custom marshaling using MarshalXML and UnmarshalXML.
  • Docs for encoding/xml that are mirrored off encoding/json.

All new examples are modeled off the existing custom marshal example in encoding/json.

@rsc rsc modified the milestones: Go1.10, Go1.11 Dec 1, 2017

@bradfitz bradfitz modified the milestones: Go1.11, Go1.12 Jun 13, 2018

leighmcculloch added a commit to leighmcculloch/fork-golang-go that referenced this issue Dec 11, 2018

encoding/xml, encoding/json: docs and examples using custom marshalers
Both the encoding/xml and encoding/json packages support custom
marshalers for JSON and XML, as well as the basic encoding.TextMarshaler
and encoding.TextUnmarshaler interfaces, but the docs and examples for
these are missing.

There are docs for how to use encoding.TextMarshaler and
encoding.TextUnmarshaler in encoding/json, but not encoding/xml. There
are no examples for how to use them with either json or xml. This commit
includes docs for encoding/xml and examples for both encoding/json and

There is an example using custom marshalers MarshalJSON and
UnmarshalJSON in encoding/json, but not MarshalXML and UnmarshalXML in
encoding/json. These docs are more so necessary for encoding/xml because
the complexities of XML documents is significantly greater than JSON
documents which more often leads to the need for custom marshaling. The
encoding/json package includes an example of how to write a custom
marshaler, and this commit includes the same example for the xml

All examples are mirrored off the existing custom marshaler example in

Fixes golang#6859

Change-Id: Ic93abc27c0b4d5e48dea6ede4e20b1bedca4ab39

@ianlancetaylor ianlancetaylor modified the milestones: Go1.12, Go1.13 Dec 11, 2018

@gopherbot gopherbot closed this in d70b0ec Dec 12, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment