encoding/json: explain how to properly Marshall RawMessage

[hydroflame]

encoding/json has an example for Unmarshalling json.RawMessage but not for Marshalling it. The example doesn't point out that Marshalling requires a *RawMessage. Using RawMessage doesn't give the expected results and it's not immediately obvious why.
https://play.golang.org/p/A1nbikzzVY

[josharian]

cc @ccirello

[ucirello]

I think it makes sense adding such example, namely because the documentation says it can be used both to delay parsing as much to precompute a JSON encoding - the latter missing. Likely something along the lines: https://play.golang.org/p/OdTp9Dh0o1

[gopherbot]

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

[joegrasse]

Back to the example that @hydroflame gave, here is another way it works.

https://play.golang.org/p/sMKGqodDde

So is it better to just always pass the pointer of the thing to json.Marshal?

cc @ccirello @josharian

[ucirello]

I believe it to be a bit misleading to say that is better to call always json.Marshal(&v). json.Marshal will execute json.Marshaler of pointers, otherwise it will just take the concrete type and marshal it.

https://play.golang.org/p/-lwP-OzIEx