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

fmt: fix up examples #27554

Open
robpike opened this issue Sep 7, 2018 · 10 comments
Open

fmt: fix up examples #27554

robpike opened this issue Sep 7, 2018 · 10 comments
Labels
Documentation Issues describing a change to documentation. NeedsFix The path to resolution is known, but the work has not been done.
Milestone

Comments

@robpike
Copy link
Contributor

robpike commented Sep 7, 2018

The examples in the fmt package are inconsistent, which makes them confusing. They need to be cleaned up and categorized better.

There are several needs as I see it, at least for the printing side:

  1. A consistent set of one-line examples demonstrating, for the same non-trivial arguments, what each of Print, Printf, and Println do.
  2. A consistent set of one-line examples demonstrating, for the same non-trivial arguments, the difference between Print, Fprint, and Sprint (etc.).
  3. A carefully written package-level example demonstrating how the formats for Printf etc. work, including flags, padding, etc.

Assigning to myself.

@robpike robpike self-assigned this Sep 7, 2018
@robpike robpike added this to the Go1.12 milestone Sep 7, 2018
@robpike robpike closed this as completed Sep 7, 2018
@robpike robpike reopened this Sep 7, 2018
@robpike robpike mentioned this issue Sep 7, 2018
25 tasks
@bcmills bcmills added the Documentation Issues describing a change to documentation. label Sep 7, 2018
@vikramcse
Copy link

@robpike I would like to fix the examples by following above guidelines. For a start where I can proceed with?

@robpike
Copy link
Contributor Author

robpike commented Sep 9, 2018

I have a very particular idea of how to proceed that I would prefer to do myself. Please leave it to me; the issue is assigned to me.

@kevinburke
Copy link
Contributor

I’m really unhappy with the way this has been handled. After eight years and no examples, we get a ton of 1) examples added from 2) people who are new to the contribution process, something we are always trying to encourage.

With zero acknowledgement of either the contributors or the progress made - after eight years of nothing - the original issue is closed and all other community members are discouraged from participating in the “new” process.

@robpike
Copy link
Contributor Author

robpike commented Sep 10, 2018

I apologize for the mess. It was badly handled and I will take the blame for that as much as anyone. One thing I didn't do that I should have was squelch the call for examples in this package at the start, but I didn't see it. Regardless, it is important that the package have good documentation and the process wasn't achieving that goal.

When first written the documentation (like all the rest of it, to be fair) assumed familiarity with C. That is no longer a reasonable baseline to expect. The package needs a proper set of examples that clearly and succinctly explain how it works and how to format data.

As the owner of the package, and someone who cares deeply about documentation, I am taking responsibility for making that happen.

Again, I apologize for how this was handled.

@ucirello
Copy link
Contributor

I just want to make a point that when I was more active in writing examples I got a review from @robpike in which he stated that part of fmt should not be advertised.

https://go-review.googlesource.com/c/go/+/27972

Also, I would very much prefer not to advertise the scanning routines of this package. They are difficult to understand, inefficient, and their job is much better done by other parts of the library. They arrived because of an early belief in the need to mimic C but that desire is long gone and we are stuck with them due to the compatibility promise. I sincerely wish I had never written them.

At this point, I figured that fmt was just as good as it was.

My point here is that probably we shouldn't try 100% coverage with examples. At the time, I always preferred examples that covered the gaps the human documentation left behind, sometimes offering a gentle introduction to some specific topic (like not understanding lock primitives in sync package). In my opinion, that's not what I see from CLs related to #27376.

Although I understand the impetus of bringing people to contribute to Go and to its documentation is laudable, I deem the fmt package to be a little bit more of a complicated case as it is one of the oldest packages and reflects part of the learning process that led up to Go1.

@kevinburke
Copy link
Contributor

My point here is that probably we shouldn't try 100% coverage with examples.

That is perfectly understandable! If someone had left that comment on the original issue I would have removed those from the checklist. But that could have been handled with a comment on the original issue, instead of closing it and opening a new issue without soliciting anyone's feedback.

@gopherbot
Copy link
Contributor

Change https://golang.org/cl/136615 mentions this issue: fmt: unify the printing examples

@gopherbot
Copy link
Contributor

Change https://golang.org/cl/136616 mentions this issue: fmt: add a package-level example illustrating basic formats

@robpike
Copy link
Contributor Author

robpike commented Sep 21, 2018

Suggestion from a reviewer: give a full list of mnemonics for the verbs.

gopherbot pushed a commit that referenced this issue Sep 24, 2018
There is much left out here—the space of possibilities is very
large—but this example shows all that most programmers will need
to know for most printing problems.

Update #27554.

Change-Id: Ib6ae651d5c3720cf7fe1a05ffd0859a5b56a9157
Reviewed-on: https://go-review.googlesource.com/136616
Reviewed-by: Ian Lance Taylor <iant@golang.org>
gopherbot pushed a commit that referenced this issue Sep 24, 2018
Provide an example for each of the printing functions (Print,
Sprintf, Fprintln etc.), and make them all produce the same output
so their usage can be compared.

Also add a package-level example explaining the difference between
how Printf, Println, and Print behave.

There are more examples to come.

Update #27554.

Change-Id: Ide03e5233f3762a9ee2ac0269f534ab927562ce2
Reviewed-on: https://go-review.googlesource.com/136615
Reviewed-by: Ian Lance Taylor <iant@golang.org>
Run-TryBot: Ian Lance Taylor <iant@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
@gopherbot
Copy link
Contributor

Change https://golang.org/cl/138837 mentions this issue: fmt: add example Sscanf

gopherbot pushed a commit that referenced this issue Oct 6, 2018
Updates #27554.

Change-Id: I2bf3d57ebeeb5dd50beffbc643a4ad10287b2c1e
GitHub-Last-Rev: 4ffae55
GitHub-Pull-Request: #27954
Reviewed-on: https://go-review.googlesource.com/c/138837
Reviewed-by: Rob Pike <r@golang.org>
Run-TryBot: Rob Pike <r@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
@ianlancetaylor ianlancetaylor added the NeedsFix The path to resolution is known, but the work has not been done. label Dec 12, 2018
@ianlancetaylor ianlancetaylor modified the milestones: Go1.12, Go1.13 Dec 12, 2018
@andybons andybons modified the milestones: Go1.13, Go1.14 Jul 8, 2019
@rsc rsc modified the milestones: Go1.14, Backlog Oct 9, 2019
@rsc rsc unassigned robpike Jun 23, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation Issues describing a change to documentation. NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Development

No branches or pull requests

9 participants