-
Notifications
You must be signed in to change notification settings - Fork 18.4k
Description
What version of Go are you using (go version
)?
$ go version go version devel go1.21-ba91377454 Sat Jan 21 21:08:30 2023 +0000 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/mvdan/.cache/go-build" GOENV="/home/mvdan/.config/go/env" GOEXE="" GOEXPERIMENT="" GOFLAGS="" GOHOSTARCH="amd64" GOHOSTOS="linux" GOINSECURE="" GOMODCACHE="/home/mvdan/go/pkg/mod" GONOPROXY="" GONOSUMDB="" GOOS="linux" GOPATH="/home/mvdan/go" GOPRIVATE="" GOPROXY="https://proxy.golang.org,direct" GOROOT="/home/mvdan/tip" GOSUMDB="sum.golang.org" GOTMPDIR="" GOTOOLDIR="/home/mvdan/tip/pkg/tool/linux_amd64" GOVCS="" GOVERSION="devel go1.21-ba91377454 Sat Jan 21 21:08:30 2023 +0000" GCCGO="gccgo" GOAMD64="v3" 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 -m64 -pthread -Wl,--no-gc-sections -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build3083007116=/tmp/go-build -gno-record-gcc-switches" GOROOT/bin/go version: go version devel go1.21-ba91377454 Sat Jan 21 21:08:30 2023 +0000 linux/amd64 GOROOT/bin/go tool compile -V: compile version devel go1.21-ba91377454 Sat Jan 21 21:08:30 2023 +0000 uname -sr: Linux 6.1.7-arch1-1 LSB Version: n/a Distributor ID: Arch Description: Arch Linux Release: rolling Codename: n/a /usr/lib/libc.so.6: GNU C Library (GNU libc) stable release version 2.36. gdb --version: GNU gdb (GDB) 12.1
What did you do?
Wrote some godoc to include a doc link referencing a missing name, as well as an example referencing a missing name.
$ git diff
diff --git a/src/archive/zip/example_test.go b/src/archive/zip/example_test.go
index 1eed3040cb..81551609f2 100644
--- a/src/archive/zip/example_test.go
+++ b/src/archive/zip/example_test.go
@@ -75,7 +75,7 @@ func ExampleReader() {
// This is the source code repository for the Go programming language.
}
-func ExampleWriter_RegisterCompressor() {
+func ExampleWriter_Missing() {
// Override the default Deflate compressor with a higher compression level.
// Create a buffer to write our archive to.
diff --git a/src/archive/zip/reader.go b/src/archive/zip/reader.go
index 3e96d0ecc9..917604b826 100644
--- a/src/archive/zip/reader.go
+++ b/src/archive/zip/reader.go
@@ -89,7 +89,7 @@ func OpenReader(name string) (*ReadCloser, error) {
// have the given size in bytes.
//
// If any file inside the archive uses a non-local name
-// (as defined by [filepath.IsLocal]) or a name containing backslashes
+// (as defined by [filepath.Missing]) or a name containing backslashes
// and the GODEBUG environment variable contains `zipinsecurepath=0`,
// NewReader returns the reader with an ErrInsecurePath error.
// A future version of Go may introduce this behavior by default.
What did you expect to see?
go vet
should warn about both.
What did you see instead?
go vet
only warns about the unknown name in the example name, but not in the doc link:
$ go vet archive/zip
# archive/zip_test
src/archive/zip/example_test.go:78:1: ExampleWriter_Missing refers to unknown field or method: Writer.Missing
I write this bug because I'm improving godocs in a project of mine to use doc links. It's hard to tell if I'm making any mistakes when referencing packages or exported names, because vet isn't helping me at all. I will likely look at the rendered godoc after pushing to a branch, but it's going to be very tricky to verify every link renders and works properly by hand.
I think vet should warn about all forms of broken links, even [Name1]
or [pkg.Name1]
. I realise that we want to be careful with backwards compatibility; old godocs may contain text which happens to be a broken link. In those cases, I'd want to be warned as well, because I want to either fix the link, or change the godoc so that it's not a link - by using a block quote for example.