Repository: go
Issue: proposal: cmd/vet: should warn about broken doc links
Labels: Proposal

### What version of Go are you using (`go version`)?

<pre>
$ go version
go version devel go1.21-ba91377454 Sat Jan 21 21:08:30 2023 +0000 linux/amd64
</pre>

### Does this issue reproduce with the latest release?

Yes.

### What operating system and processor architecture are you using (`go env`)?

<details><summary><code>go env</code> Output</summary><br><pre>
$ 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
</pre></details>

### What did you do?

Wrote some godoc to include a [doc link](https://go.dev/doc/comment#doclinks) 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.