Go: fmt: add examples

[kevinburke]

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.

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

• [x] 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

• [x] 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)

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

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

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

• [x] 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)

• [x] func Sprint(a ...interface{}) string

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

• [x] 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

• [x] type GoStringer

• [ ] type ScanState

• [ ] type Scanner

• [ ] type State

• [x] type Stringer

[venilnoronha]

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

[techmexdev]

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

[ianzapolsky]

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

[drewvanstone]

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

[waits]

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

[kevinburke]

@waits there is actually a CL open for that one at the moment from @mooreds https://github.com/golang/go/issues/27349 - I should have added it to the sheet. how about Fprintf?

[MaerF0x0]

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

[waits]

Fprintf was taken also, I'll take Fprintln

[ianzapolsky]

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]

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]

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]

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]

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]

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]

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

[kevinburke]

Looking great! https://tip.golang.org/pkg/fmt/

[mfrw]

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

[andriisoldatenko]

@kevinburke I can create example for Fscan.

[drewvanstone]

Sprintln is done

[gopherbot]

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

[wfernandes]

I'll do GoStringer

[gopherbot]

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

[gopherbot]

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

[gopherbot]

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

[gopherbot]

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

[robpike]

Replacing with issue https://github.com/golang/go/issues/27554.

Please stop adding examples to the package for now.

[bmeh]

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]

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]

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. :relaxed:

[ianlancetaylor]

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]

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]

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]

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]

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 https://github.com/golang/go/issues/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.

[gopherbot]

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