Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.
Sign upencoding/json: indentation of raw strings in examples looks suboptimal in godoc #21026
Assignees
Comments
This comment has been minimized.
This comment has been minimized.
|
CL https://golang.org/cl/48910 mentions this issue. |
This comment has been minimized.
This comment has been minimized.
|
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. |
This comment has been minimized.
This comment has been minimized.
|
@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. |
This comment has been minimized.
This comment has been minimized.
|
Ah, makes sense - was missing the workshop context :) |
gopherbot
pushed a commit
that referenced
this issue
Jul 15, 2017
The existing example for Decoder.Decode (Stream) had excessive indentation in the godoc interface for the const jsonStream, making it hard to read. This fixes the indentation in the example_test.go to improve the readability in godoc. Helps #21026. Change-Id: I16f56b82182da1dcc73cca44e535a7f5695e975d Reviewed-on: https://go-review.googlesource.com/48910 Reviewed-by: Dmitri Shuralyov <shurcool@gmail.com> Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
This comment has been minimized.
This comment has been minimized.
|
CL https://golang.org/cl/50990 mentions this issue. |
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Motivation
There are two ways a Go example can be read:
godoccommand 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/jsonpackage 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.