Skip to content

x/tools/gopls: add analyzer that reports broken doc links #57963

@mvdan

Description

@mvdan

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    AnalysisIssues related to static analysis (vet, x/tools/go/analysis)FeatureRequestIssues asking for a new feature that does not need a proposal.goplsIssues related to the Go language server, gopls.help wanted

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions