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

Jump to bottom

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

Open
thediveo opened this issue Jul 20, 2022 · 3 comments
Open

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

thediveo opened this issue Jul 20, 2022 · 3 comments
Labels
NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made.
Milestone
Backlog

Comments

@thediveo
Copy link

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
Copy link
Member

cc @rsc

@thediveo
Copy link
Author

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

@ianlancetaylor
Copy link
Contributor

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.

@toothrot toothrot added the NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made. label Jul 22, 2022
@toothrot toothrot added this to the Backlog milestone Jul 22, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made.
Projects
None yet
Milestone
Backlog
Development

No branches or pull requests
4 participants
@toothrot @ianlancetaylor @thediveo @seankhliao