-
Notifications
You must be signed in to change notification settings - Fork 17.9k
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
Comments
@robpike I would like to fix the examples by following above guidelines. For a start where I can proceed with? |
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. |
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. |
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. |
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 https://go-review.googlesource.com/c/go/+/27972
At this point, I figured that 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 Although I understand the impetus of bringing people to contribute to Go and to its documentation is laudable, I deem the |
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. |
Change https://golang.org/cl/136615 mentions this issue: |
Change https://golang.org/cl/136616 mentions this issue: |
Suggestion from a reviewer: give a full list of mnemonics for the verbs. |
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>
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>
Change https://golang.org/cl/138837 mentions this issue: |
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>
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:
Assigning to myself.
The text was updated successfully, but these errors were encountered: