go/doc/comment: Plurals of linked symbols do not work

[thediveo]

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

$ go version
go version go1.19rc2 linux/amd64

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="amd64"
GOBIN=""
GOCACHE="/home/.../.cache/go-build"
GOENV="/home/.../.config/go/env"
GOEXE=""
GOEXPERIMENT=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOINSECURE=""
GOMODCACHE="/home/.../go/pkg/mod"
GONOPROXY=""
GONOSUMDB=""
GOOS="linux"
GOPATH="/home/.../go"
GOPRIVATE=""
GOPROXY="https://proxy.golang.org,direct"
GOROOT="/home/.../sdk/go1.19rc2"
GOSUMDB="sum.golang.org"
GOTMPDIR=""
GOTOOLDIR="/home/.../sdk/go1.19rc2/pkg/tool/linux_amd64"
GOVCS=""
GOVERSION="go1.19rc2"
GCCGO="gccgo"
GOAMD64="v1"
AR="ar"
CC="gcc"
CXX="g++"
CGO_ENABLED="1"
GOMOD="/dev/null"
GOWORK="/home/.../workspaces/namespaces/go.work"
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -m64 -pthread -Wl,--no-gc-sections -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build4195388595=/tmp/go-build -gno-record-gcc-switches"

What did you do?

Writing a doc comment linking to a type as follows:

// ComposerProject represents a set of either running or paused (but always
// "somehow" alive) [Container]s belonging to a specific Docker
// Compose/Composer project.

I'm aware of the go tip documentation about doc comments with the current definition:

To avoid problems with maps, generics, and array types, doc links must be both preceded and followed by punctuation, spaces, tabs, or the start or end of a line.

What did you expect to see?

Pluralization, such as the [Container]s link to be properly resolved into a hyperlink to the Container type.

What did you see instead?

[Container]s

[seankhliao]

cc @rsc

[thediveo]

Just for completeness: trying to (mis?) use a zero-width space didn’t help as a workaround; the pluralized link didn't work.

[ianlancetaylor]

I don't think we can change go/doc/comment here. [Container]s is a valid Go array type, and an incorrect link for what was meant to be a array would break the comment. I think the only way to move forward is to rephrase the sentence.

// ComposerProject represents a set of either running or paused (but always
// "somehow" alive) [Container] values belonging to a specific Docker
// Compose/Composer project.

[theory]

I just noticed I have a lot of broken links due to this issue. I see this bit from the docs:

To avoid problems with maps, generics, and array types, doc links must be both preceded and followed by punctuation, spaces, tabs, or the start or end of a line. For example, the text “map[ast.Expr]TypeAndValue” does not contain a doc link.

It's a bit annoying for plurals, though. Could it not be the rule that the limitation be only preceding a doc link? That would allow each of these to work:

• map[ast.Expr]TypeAndValue: No link
• []string: no link
• [3]int: no link
• [2*N] struct { x, y int32 }: No link? (this one is already ambiguous)
• [Container]s: link

[mvdan]

FWIW [Foo]s works today with go-to-definition in gopls, even though pkg.go.dev does nto linkify it. See my duplicate issue at #73610.

[seankhliao]

Could it not be the rule that the limitation be only preceding a doc link

That doesn't work for arrays / slices.

[theory]

That doesn't work for arrays / slices.

No, it's not perfect, it's a trade-off.