encoding/json: indentation of raw strings in examples looks suboptimal in godoc

[dmitshur]

Motivation

There are two ways a Go example can be read:

1. In the source code of a _test.go file.
2. Via godoc command or the web interface it provides.

In most cases, examples look equally good in both interfaces. However, in some cases, there may be two alternative ways to write an example, such that one of them looks better inside source code, and the other looks better in the godoc interface.

My understanding is that it's better to prioritize the godoc interface over the source code, since most people will be reading examples via godoc (be it locally, or via https://godoc.org, or https://golang.org/pkg/). If that is not correct, the rest of this issue is not valid.

Issue

I found that there are 5 examples in encoding/json package that have raw strings with indentation which is suboptimal when seen via the godoc interface.

They are:

• https://tip.golang.org/pkg/encoding/json/#example_Decoder:

  

• https://tip.golang.org/pkg/encoding/json/#example_Decoder_Decode_stream:
  (Resolved by CL 48910.)

  

• https://tip.golang.org/pkg/encoding/json/#example_Decoder_Token:

  

• https://tip.golang.org/pkg/encoding/json/#example_Unmarshal:

  

• https://tip.golang.org/pkg/encoding/json/#example_RawMessage_unmarshal:

  

Their readability in godoc interface can be improved by dedenting the contents of the raw string by 1 tab.

[gopherbot]

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

[mvdan]

It seems that someone took a stab at the changes. I assume this issue is to confirm your suspicion on godoc formatting being more important than source code formatting, before the patches are applied.

If that's so, I agree.

[dmitshur]

@mvdan, I filed the issue for posterity and to confirm that prioritizing godoc view is the right thing to do.

I suggested it to someone as their first Go CL. We're doing it as part of a Go Contributor Workshop at GopherCon 2017.

[mvdan]

Ah, makes sense - was missing the workshop context :)

[gopherbot]

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