Skip to content
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/json: indentation of raw strings in examples looks suboptimal in godoc #21026

Closed
dmitshur opened this issue Jul 15, 2017 · 5 comments

Comments

Projects
None yet
3 participants
@dmitshur
Copy link
Member

commented Jul 15, 2017

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:

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

@gopherbot

This comment has been minimized.

Copy link

commented Jul 15, 2017

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

@mvdan

This comment has been minimized.

Copy link
Member

commented Jul 15, 2017

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

This comment has been minimized.

Copy link
Member Author

commented Jul 15, 2017

@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

This comment has been minimized.

Copy link
Member

commented Jul 15, 2017

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

gopherbot pushed a commit that referenced this issue Jul 15, 2017

encoding/json: fix indentation in Decode stream example
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>
@gopherbot

This comment has been minimized.

Copy link

commented Jul 24, 2017

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

@dmitshur dmitshur self-assigned this Jul 24, 2017

@gopherbot gopherbot closed this in c4e29bb Aug 8, 2017

@golang golang locked and limited conversation to collaborators Aug 8, 2018

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
You can’t perform that action at this time.