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: package documentation doesn't have linkable subheadings under top-level "Printing" and "Scanning" sections #46522

Closed
zephyrtronium opened this issue Jun 2, 2021 · 1 comment
Labels
Documentation FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Milestone

Comments

@zephyrtronium
Copy link
Contributor

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

$ go version
go version go1.16.3 windows/amd64

Does this issue reproduce with the latest release?

Yes, including on tip.

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

go env Output
$ go env
set GO111MODULE=on
set GOARCH=amd64
set GOBIN=
set GOCACHE=C:\Users\zephyr\AppData\Local\go-build
set GOENV=C:\Users\zephyr\AppData\Roaming\go\env
set GOEXE=.exe
set GOFLAGS=
set GOHOSTARCH=amd64
set GOHOSTOS=windows
set GOINSECURE=
set GOMODCACHE=E:\go\pkg\mod
set GONOPROXY=
set GONOSUMDB=
set GOOS=windows
set GOPATH=E:\go
set GOPRIVATE=
set GOPROXY=https://proxy.golang.org,direct
set GOROOT=c:\go
set GOSUMDB=sum.golang.org
set GOTMPDIR=
set GOTOOLDIR=c:\go\pkg\tool\windows_amd64
set GOVCS=
set GOVERSION=go1.16.3
set GCCGO=gccgo
set AR=ar
set CC=gcc
set CXX=g++
set CGO_ENABLED=1
set GOMOD=NUL
set CGO_CFLAGS=-g -O2
set CGO_CPPFLAGS=
set CGO_CXXFLAGS=-g -O2
set CGO_FFLAGS=-g -O2
set CGO_LDFLAGS=-g -O2
set PKG_CONFIG=pkg-config
set GOGCCFLAGS=-m64 -mthreads -fmessage-length=0 -fdebug-prefix-map=C:\Users\zephyr\AppData\Local\Temp
\go-build1861236026=/tmp/go-build -gno-record-gcc-switches

What did you do?

I explained the explicit argument syntax for printf formatting verbs to someone, then tried to get a useful link to an authoritative source in golang.org/pkg/fmt to explain more thoroughly.

What did you expect to see?

An anchored section on explicit argument indices in the package documentation.

What did you see instead?

A "section" on explicit argument indices, but not one recognized by godoc because the line ends with punctuation:

go/src/fmt/doc.go

Lines 191 to 193 in 6e189af

Explicit argument indexes:

It seems plausible that this is intentional, as the current structure leaves "Printing" and "Scanning" as the only proper sections. However, not having explicit sections for this particular topic – which seems to be underused – makes it harder to explain and promote its usefulness, particularly because there is no hyperlink to it.

The current document also flows less effectively as a result of these broken sections. There is another subsequent pseudo-section like this on "Format errors:", but also many earlier lines describing the flags for various types; those lines follow this format, but they do not seem to be intended to be distinct subsections. The explicit argument indices section itself is shortly preceded by the line "convert the value before recurring:", which makes it hard to recognize that the former is a distinct section.

@dr2chase dr2chase added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Jun 2, 2021
@dmitshur dmitshur added this to the Backlog milestone Jun 2, 2021
@dmitshur dmitshur changed the title fmt: package documentation has broken sections fmt: package documentation doesn't have linkable subheadings under top-level "Printing" and "Scanning" sections Jun 2, 2021
@gopherbot
Copy link

Change https://golang.org/cl/324349 mentions this issue: fmt: split package documentation into more sections

@dmitshur dmitshur added NeedsFix The path to resolution is known, but the work has not been done. and removed NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. labels Jun 7, 2021
@dmitshur dmitshur modified the milestones: Backlog, Go1.17 Jun 7, 2021
@golang golang locked and limited conversation to collaborators Jun 7, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Documentation FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Development

No branches or pull requests

4 participants