encoding/json: indentation of raw strings in examples looks suboptimal in godoc #21026
Closed
1 of 5 tasks
Labels
Documentation
Issues describing a change to documentation.
FrozenDueToAge
NeedsFix
The path to resolution is known, but the work has not been done.
Suggested
Issues that may be good for new contributors looking for work to do.
Comments
|
CL https://golang.org/cl/48910 mentions this issue. |
|
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. |
|
@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. |
|
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>
dmitshur
added
NeedsFix
|
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.
The text was updated successfully, but these errors were encountered: