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: add examples #27376

Closed
kevinburke opened this issue Aug 30, 2018 · 35 comments
Closed

fmt: add examples #27376

kevinburke opened this issue Aug 30, 2018 · 35 comments
Assignees
Milestone

Comments

@kevinburke
Copy link
Contributor

@kevinburke kevinburke commented Aug 30, 2018

Let's add examples. I think it would be good to add examples to each function (if possible?) as well as to illustrate some points - not every example should make every point but it would be good to cover these.

  • how do %d, %s, %q, %v differ

  • how do you do left/right padding

  • decimal formatting

  • how does "ln" ending vary from "f" ending

When you open a change, put this at the bottom of the commit message:

Updates golang/go#27376.

That way gopherbot will post a comment here with a link to your CL.

Add a comment if you want to fix one and I'll put your name next to the func in question.

  • func Errorf(format string, a ...interface{}) error: @ianzapolsky

  • func Fprint(w io.Writer, a ...interface{}) (n int, err error)

  • func Fprintf(w io.Writer, format string, a ...interface{}) (n int, err error): @MaerF0x0

  • func Fprintln(w io.Writer, a ...interface{}) (n int, err error): @waits

  • func Fscan(r io.Reader, a ...interface{}) (n int, err error): @andriisoldatenko

  • func Fscanf(r io.Reader, format string, a ...interface{}) (n int, err error)

  • func Fscanln(r io.Reader, a ...interface{}) (n int, err error): @mfrw

  • func Print(a ...interface{}) (n int, err error)

  • func Printf(format string, a ...interface{}) (n int, err error): @mooreds

  • func Println(a ...interface{}) (n int, err error): @techmexdev

  • func Scan(a ...interface{}) (n int, err error)

  • func Scanf(format string, a ...interface{}) (n int, err error)

  • func Scanln(a ...interface{}) (n int, err error)

  • func Sprint(a ...interface{}) string

  • func Sprintf(format string, a ...interface{}) string: @venilnoronha

  • func Sprintln(a ...interface{}) string: @drewvanstone

  • func Sscan(str string, a ...interface{}) (n int, err error)

  • func Sscanf(str string, format string, a ...interface{}) (n int, err error)

  • func Sscanln(str string, a ...interface{}) (n int, err error)

  • type Formatter

  • type GoStringer

  • type ScanState

  • type Scanner

  • type State

  • type Stringer

@venilnoronha
Copy link
Contributor

@venilnoronha venilnoronha commented Aug 30, 2018

Sprintf(format string, a ...interface{}) string

@techmexdev
Copy link
Contributor

@techmexdev techmexdev commented Aug 30, 2018

I can do func Println(a ...interface{}) (n int, err error)

@ianzapolsky
Copy link
Contributor

@ianzapolsky ianzapolsky commented Aug 30, 2018

I'll do func Errorf(format string, a ...interface{}) error

@drewvanstone
Copy link
Contributor

@drewvanstone drewvanstone commented Aug 30, 2018

I'll do func Sprintln(a ...interface{}) string

@waits
Copy link
Contributor

@waits waits commented Aug 30, 2018

I'll do func Printf(format string, a ...interface{}) (n int, err error)

@kevinburke
Copy link
Contributor Author

@kevinburke kevinburke commented Aug 30, 2018

@waits there is actually a CL open for that one at the moment from @mooreds #27349 - I should have added it to the sheet. how about Fprintf?

@MaerF0x0
Copy link

@MaerF0x0 MaerF0x0 commented Aug 30, 2018

I'll do func Fprintf(w io.Writer, format string, a ...interface{}) (n int, err error)

@waits
Copy link
Contributor

@waits waits commented Aug 30, 2018

Fprintf was taken also, I'll take Fprintln

@ianzapolsky
Copy link
Contributor

@ianzapolsky ianzapolsky commented Aug 30, 2018

Anyone know how often the official go documentation is updated? i.e. how long our commits should take to show up here: https://golang.org/pkg/fmt/

@kevinburke
Copy link
Contributor Author

@kevinburke kevinburke commented Aug 30, 2018

They should appear at tip.golang.org almost immediately, as I believe that project fetches from HEAD every 15 minutes.

The docs on golang.org will update the next time there's a new Go release, or earlier if the patches are backported from master (which targets Go 1.12) to the Go 1.11.1 point release.

@kevinburke
Copy link
Contributor Author

@kevinburke kevinburke commented Aug 30, 2018

The problem with updating golang.org is if we add some new API for Go 1.12 (like strings.Builder) it would not be good if it showed up in the docs before most people were able to use it.

@MaerF0x0
Copy link

@MaerF0x0 MaerF0x0 commented Aug 30, 2018

Is there a way we can run our new ExampleFunc locally to ensure it works? Else I can copy it to play.golang.org

@kevinburke
Copy link
Contributor Author

@kevinburke kevinburke commented Aug 30, 2018

Yes, run go get golang.org/x/tools/cmd/godoc and then start godoc:

GOROOT=/path/to/your/contribution-repo godoc -http=:6060

Open localhost:6060/fmt in your browser and your changes should be there.

@kevinburke
Copy link
Contributor Author

@kevinburke kevinburke commented Aug 30, 2018

Alternatively you can create a new fmt repo on Github, copy the source files, push your changes there, then go to e.g. godoc.org/github.com/yourname/fmt to see the docs.

@gopherbot
Copy link

@gopherbot gopherbot commented Aug 30, 2018

Change https://golang.org/cl/132375 mentions this issue: fmt: add doc example for Fprintf

@kevinburke
Copy link
Contributor Author

@kevinburke kevinburke commented Aug 30, 2018

@mfrw
Copy link
Contributor

@mfrw mfrw commented Aug 31, 2018

I'll do func Fscanln(r io.Reader, a ...interface{}) (n int, err error)

@andriisoldatenko
Copy link
Contributor

@andriisoldatenko andriisoldatenko commented Aug 31, 2018

@kevinburke I can create example for Fscan.

@drewvanstone
Copy link
Contributor

@drewvanstone drewvanstone commented Aug 31, 2018

Sprintln is done

@FiloSottile FiloSottile changed the title fmt: tracking issue for adding examples fmt: add examples Aug 31, 2018
@FiloSottile FiloSottile added this to the Unplanned milestone Aug 31, 2018
@gopherbot
Copy link

@gopherbot gopherbot commented Aug 31, 2018

Change https://golang.org/cl/132675 mentions this issue: fmt: add example for Fscanln

gopherbot pushed a commit that referenced this issue Aug 31, 2018
Updates #27376.

Change-Id: I9f33233f1aafa10941a63fcb4e49d351ea7ee246
Reviewed-on: https://go-review.googlesource.com/132675
Reviewed-by: Kevin Burke <kev@inburke.com>
Run-TryBot: Kevin Burke <kev@inburke.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>
@wfernandes
Copy link
Contributor

@wfernandes wfernandes commented Sep 3, 2018

I'll do GoStringer

@gopherbot
Copy link

@gopherbot gopherbot commented Sep 3, 2018

Change https://golang.org/cl/133075 mentions this issue: fmt: add example for GoStringer interface

@gopherbot
Copy link

@gopherbot gopherbot commented Sep 5, 2018

Change https://golang.org/cl/133455 mentions this issue: fmt: add example for Fprint

gopherbot pushed a commit that referenced this issue Sep 6, 2018
Updates #27376.

Change-Id: Ia8608561eb6a268aa7eae8c39c7098df100b643a
Reviewed-on: https://go-review.googlesource.com/133075
Reviewed-by: Kevin Burke <kev@inburke.com>
Run-TryBot: Kevin Burke <kev@inburke.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>
gopherbot pushed a commit that referenced this issue Sep 7, 2018
Updates #27376

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

@gopherbot gopherbot commented Sep 7, 2018

Change https://golang.org/cl/134035 mentions this issue: fmt: add example for Print

@gopherbot
Copy link

@gopherbot gopherbot commented Sep 7, 2018

Change https://golang.org/cl/134036 mentions this issue: fmt: add example for Sprint

gopherbot pushed a commit that referenced this issue Sep 7, 2018
Updates #27376

Change-Id: I2fa63b0d1981a419626072d985e6f3326f6013ff
Reviewed-on: https://go-review.googlesource.com/134035
Run-TryBot: Ian Lance Taylor <iant@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Ian Lance Taylor <iant@golang.org>
gopherbot pushed a commit that referenced this issue Sep 7, 2018
Updates #27376

Change-Id: I9ce6541a95b5ecd13f3932558427de1f597df07a
Reviewed-on: https://go-review.googlesource.com/134036
Run-TryBot: Ian Lance Taylor <iant@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Ian Lance Taylor <iant@golang.org>
@robpike robpike self-assigned this Sep 7, 2018
@robpike
Copy link
Contributor

@robpike robpike commented Sep 7, 2018

Replacing with issue #27554.

Please stop adding examples to the package for now.

@robpike robpike closed this Sep 7, 2018
@bmeh
Copy link

@bmeh bmeh commented Sep 8, 2018

The problem with updating golang.org is if we add some new API for Go 1.12 (like strings.Builder) it would not be good if it showed up in the docs before most people were able to use it.

First off, I don't see how this could be an issue if you are having docs per version (docs for 1.11, docs for 1.12, and so on), and secondly, what is strings.Builder and do we really need it? Are we going to have strings.Factory, too? For a moment I thought go is finally taking a better route, but it makes me reconsider that thought.

On another note, yes, I agree with Rob here. Inconsistency has been a problem for go, it just seems like people come and write completely different and random examples to similar, related functions. That's not how it should be done. Apparently Rob had to assign it to himself, and tell others to stop posting examples for this reason. Thanks Rob, this chaotic madness needs to stop.

Go linters complain when exported variables or constants are not documented (despite them being obvious in many cases), yet when core developers make major changes to go, they keep the old documentation, and don't even bother making it up-to-date.

Excuse me for my tone, but it irks me a bit, anyways: thanks for putting an end to it, for the time being.

@ianlancetaylor
Copy link
Contributor

@ianlancetaylor ianlancetaylor commented Sep 9, 2018

Please do keep a polite tone. Thanks.

The comment about updating golang.org was in the context of somebody asking how they could see the current docs. The answer was: use tip.golang.org, with an explanation for why golang.org is not updated.

For strings.Builder see https://golang.org/pkg/strings/#Builder .

@bmeh
Copy link

@bmeh bmeh commented Sep 9, 2018

Is there any particular reason for why it's not called strings.Buffer, next to bytes.Buffer (which exists)?

It was a neutral-tone, you might have never actually attached or imagined negative connotations to it if it weren't for me saying "excuse me for my tone", which I have only said because I know how often people imagine hostility where there is none. ☺️

@ianlancetaylor
Copy link
Contributor

@ianlancetaylor ianlancetaylor commented Sep 9, 2018

bytes.Buffer is also an io.Reader, strings.Builder is not.

I disagree about the tone; phrases like "this chaotic madness" and statements that the core developers do not keep documentation up to date, without giving any examples, are not helpful. Please see https://golang.org/conduct; search for "Avoid destructive behavior". Thanks.

@bmeh
Copy link

@bmeh bmeh commented Sep 9, 2018

It doesn't need to be an io.Reader, there are differences between the two regardless of the naming convention, but that doesn't necessarily warrant a completely different convention. Either way, one has to consult the documentation to get an idea of what they actually are and do, and they do largely share a similar naming convention, just compare the two on the documentation page, or the source code[1].

We can disagree all we want, my tone and intentions are irrelevant. In fact, I would argue that "chaotic madness" is a clear expression of dislike of inconsistency (which in itself is not an empty statement), albeit could be perceived exaggerated which I am not arguing against, anything could be perceived to be exaggerated and/or hostile. I am sure the reasons are identical to why Rob picked it up, judging by the new issue he opened, let me quote parts of it: "A consistent set [...]", "The examples in the fmt package are inconsistent", which means inconsistency isn't something he prefers. What you can argue in favor of is that I'm merely expressing my dislike of such, without doing anything, but that's the thing: expressing dislike is enough. There are often polls regarding the syntax of a language where they ask the community about such, etc., so it seems that expressing my dislike alone could be sufficient for various purposes and is definitely not an empty, or meaningless statement.

If we were to lecture people about "useless statements" (not quoting you), or "destructive behavior" (not sure how it applies to my case, feel free to explain if you would like, but I elaborated above why this is not the case) and enforce the conduct, there would not be too many people left here, so you can pick on me all you want and moderate me out of this discussion, but then at least have the decency to call yourself biased and note that you are not doing it consistently. It's useful against people whom we dislike, sure. I might pull out the transgender card in the future if necessary, in case that magically makes me more tolerable, which seems to be a common case these days.


What exactly do you mean by "bytes.Buffer is also an io.Reader", could you provide a reference to that? The API of strings.Builder and bytes.Buffer are remarkably similar, and they both seem to implement io.Reader per type Reader in the documentation, are you talking about that? If not, then what exactly are you referring to?

[1] Speaking of inconsistencies (albeit a minor in this case, I suppose): https://golang.org/src/strings/reader.go#L37 vs https://golang.org/src/bytes/reader.go#L39.

And note how per documentation and source code, they BOTH implement a type Reader, so ultimately, according to you AND the documentation, the naming convention is as follows:

Buffer: write and read
Builder: write
Reader: read (implemented for both strings and bytes)

Is this correct?

Edit: on second thought, by "bytes.Buffer is also an io.Reader", did you mean func (b *Buffer) ReadFrom(r io.Reader) (n int64, err error) in buffer.go? Would it be impossible to implement the same thing for strings.Builder so it would justify its rename to strings.Buffer, or is it enough of a reason to name it strings.Builder instead of strings.Buffer, the mere existence of one function?

@kevinburke
Copy link
Contributor Author

@kevinburke kevinburke commented Sep 9, 2018

Your tone and intentions do matter because they make a difference in the way people feel about what you’re saying, for one, and also because we all agreed to abide by the Code of Conduct, which says that they matter. golang.org/conduct

The entire discussion of the strings interface is off topic for this issue. I raised it only as an example of an API that had been recently added. If you want to discuss it send a message to the golang-nuts mailing list.

@bmeh
Copy link

@bmeh bmeh commented Sep 9, 2018

I cannot control how other people feel about me, and what emotions they attach to my statements. I can be friendly while being malicious, and I can be the exact opposite. Some people consider a neutral tone hostile for whatever reasons, let it be paranoia or the usually beneficial victim mentality. It is outside my control, and I do not intend to control it. I have autism, so it may be more difficult for me than others, but this is how it is, I mean no harm (which is, and was my intention all along which you did not know before - albeit assumed it, I guess -, now you do).

I agree, it has nothing to do with the actual issue, so we should terminate this conversation. Have a good day. :)

@kevinburke
Copy link
Contributor Author

@kevinburke kevinburke commented Sep 9, 2018

Yet you’re continuing to double down, in the face of multiple people telling you your behavior is not being appropriate. What I don’t understand is you’re clearly capable of writing and behaving constructively, for example on #27558.

Despite what you say your words and actions do have a large impact on how people feel about what you write and how people interact with you.

@golang golang locked as too heated and limited conversation to collaborators Sep 9, 2018
@gopherbot
Copy link

@gopherbot gopherbot commented Oct 1, 2018

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

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
You can’t perform that action at this time.