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.

Sign up for GitHub

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

Jump to bottom

fmt: error in the documentation for fmt.Formatter? #60358

Closed
myitcv opened this issue May 23, 2023 · 7 comments
Closed

fmt: error in the documentation for fmt.Formatter? #60358

myitcv opened this issue May 23, 2023 · 7 comments
Labels
Documentation Issues describing a change to documentation. FrozenDueToAge NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.

Comments

@myitcv
Copy link
Member

myitcv commented May 23, 2023

What version of Go are you using (go version)?

$ go version
go version devel go1.21-40bdc56180 Tue May 23 13:22:25 2023 +0000 linux/arm64

Does this issue reproduce with the latest release?

Yes

What operating system and processor architecture are you using (go env)?

go env Output
$ go env
GO111MODULE=""
GOARCH="arm64"
GOBIN=""
GOCACHE="/home/myitcv/.cache/go-build"
GOENV="/home/myitcv/.config/go/env"
GOEXE=""
GOEXPERIMENT=""
GOFLAGS=""
GOHOSTARCH="arm64"
GOHOSTOS="linux"
GOINSECURE=""
GOMODCACHE="/home/myitcv/gostuff/pkg/mod"
GONOPROXY=""
GONOSUMDB=""
GOOS="linux"
GOPATH="/home/myitcv/gostuff"
GOPRIVATE=""
GOPROXY="https://proxy.golang.org,direct"
GOROOT="/home/myitcv/dev/go"
GOSUMDB="sum.golang.org"
GOTMPDIR=""
GOTOOLDIR="/home/myitcv/dev/go/pkg/tool/linux_arm64"
GOVCS=""
GOVERSION="go1.20.4"
GCCGO="gccgo"
AR="ar"
CC="gcc"
CXX="g++"
CGO_ENABLED="1"
GOMOD="/dev/null"
GOWORK=""
CGO_CFLAGS="-O2 -g"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-O2 -g"
CGO_FFLAGS="-O2 -g"
CGO_LDFLAGS="-O2 -g"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -pthread -Wl,--no-gc-sections -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build697360160=/tmp/go-build -gno-record-gcc-switches"

What did you do?

$ go doc fmt Formatter

What did you expect to see?

Documentation that is consistent with the intended use of fmt.Formatter

What did you see instead?

package fmt // import "fmt"

type Formatter interface {
        Format(f State, verb rune)
}
    Formatter is implemented by any value that has a Format method. The
    implementation controls how State and rune are interpreted, and may call
    Sprint(f) or Fprint(f) etc. to generate its output.

It's unclear to me how a call to Sprint(f) can possibly work with with a fmt.State value.

A call to Fprint(f) yes, but not Sprint(f).

Am I missing something obvious, or is this a mistake in the docs?
@gopherbot gopherbot added the Documentation Issues describing a change to documentation. label May 23, 2023
@contrast-jproberts

This comment was marked as outdated.

Sign in to view
@ianlancetaylor
Copy link
Member

CC @robpike

@seankhliao seankhliao added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label May 23, 2023
@robpike
Copy link
Contributor

robpike commented May 24, 2023

Yes, it's an error. It should read "Sprint() or Fprint(f)".

@gopherbot
Copy link
Contributor

Change https://go.dev/cl/497379 mentions this issue: fmt: correct documentation for Formatter

@dolmen
Copy link
Contributor

dolmen commented May 24, 2023

So is a call to Sprintf dangerous? Is it because Sprintf is not reentrant?

If this was allowed before by the documentation, but not anymore, this not just a bug fix but a breaking change.

@myitcv
Copy link
Member Author

myitcv commented May 24, 2023

So is a call to Sprintf dangerous? Is it because Sprintf is not reentrant?

@dolmen - what does the call Sprint(f) actually do to your understanding?

@ianlancetaylor
Copy link
Member

@dolmen To be clear, calling fmt.Sprintf is fine. The comment was confusing.

@golang golang locked and limited conversation to collaborators May 23, 2024
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
Documentation Issues describing a change to documentation. FrozenDueToAge NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
7 participants
@dolmen @ianlancetaylor @myitcv @robpike @gopherbot @seankhliao @contrast-jproberts