x/tools/cmd/godoc: Doc links not working

[Fryuni]

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

$ go version
go version go1.18.1 linux/amd64

Does this issue reproduce with the latest release?

Yes, installed with go install golang.org/x/tools/cmd/godoc@latest

What operating system and processor architecture are you using (go env)?

go env Output

$ go env
GO111MODULE="on"
GOARCH="amd64"
GOBIN=""
GOCACHE="/home/lotus/.cache/go-build"
GOENV="/home/lotus/.config/go/env"
GOEXE=""
GOEXPERIMENT=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOINSECURE=""
GOMODCACHE="/home/lotus/go/pkg/mod"
GONOPROXY=""
GONOSUMDB=""
GOOS="linux"
GOPATH="/home/lotus/go"
GOPRIVATE=""
GOPROXY="https://proxy.golang.org,direct"
GOROOT="/home/lotus/go/go1.18.1"
GOSUMDB="sum.golang.org"
GOTMPDIR=""
GOTOOLDIR="/home/lotus/go/go1.18.1/pkg/tool/linux_amd64"
GOVCS=""
GOVERSION="go1.18.1"
GCCGO="gccgo"
GOAMD64="v1"
AR="ar"
CC="gcc"
CXX="g++"
CGO_ENABLED="1"
GOWORK=""
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 -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build1915755458=/tmp/go-build -gno-record-gcc-switches"

What did you do?

1. Documented a function using Doc links, as defined on the Go Doc Comments page.

   // ErrIteratorDone is returned by [Iterator.Next] when the iterator will not yield more items.
   //
   // The value of ErrIteratorDone is the same as the value of [io.EOF] for compatibility with libraries
   // that use [io.EOF] to identify when a sequence of items has been exhausted successfully.
   var ErrIteratorDone = io.EOF

2. Run godoc -links=true

What did you expect to see?

The docs with links to Iterator.Next and to io.EOF

What did you see instead?

Neither link is being interpreted by godoc. The same issue happens with pkgsite, should I open a separate bug for that?

[seankhliao]

The -links for godoc is not for comment links. It's the linking in variable / function signature.

Enhanced documentation is part of go1.19+, the binaries will need to be built with that.

Even then, godoc won't work as it uses a different url structure.

godoc is frozen / deprecated as of #49212

[thediveo]

Please forgive me if chiming in with a godoc pkgsite replacement script. Based on the idea of Milan Daverde(?) I'm using this script that automatically installs the components if not done so for the user and then runs pkgsite in "local" filesystem mode; this works around the problem that pkgsite isn't designed to hot reload changed files from the local file system:

#!/bin/bash
set -e

if ! command -v pkgsite &>/dev/null; then
    export PATH="$(go env GOPATH)/bin:$PATH"
    if ! command -v pkgsite &>/dev/null; then
        go install golang.org/x/pkgsite/cmd/pkgsite@master
    fi
fi

# In case the user hasn't set an explicit installation location, avoid polluting
# our own project...
NPMBIN=$(cd $HOME && npm bin)
export PATH="$NPMBIN:$PATH"
if ! command -v browser-sync &>/dev/null; then
    (cd $HOME && npm install browser-sync)
fi

if ! command -v nodemon &>/dev/null; then
    (cd $HOME && npm install nodemon)
fi

# https://stackoverflow.com/a/2173421
trap "trap - SIGTERM && kill -- -$$" SIGINT SIGTERM EXIT

# https://mdaverde.com/posts/golang-local-docs
browser-sync start --port 6060 --proxy localhost:6061 --reload-delay 2000 --reload-debounce 5000 --no-ui --no-open &
PKGSITE=$(which pkgsite)
nodemon --signal SIGTERM --watch './**/*' -e go --exec "browser-sync --port 6060 reload && $PKGSITE -http=localhost:6061 ."

Maybe the Go team might want to document how to get pkgsite working in a local godoc-replacement scenario?

[Fryuni]

As I mentioned on the last line, this is also not behaving correctly with pkgsite.
There it only works with the full path, so [io.EOF] works, but Iterator.Next doesn't. I have to use the add the package name to link to something on the same file.
Should I open that as a separate issue?

[seankhliao]

sure, include more reproduction instructions though, since it's working locally for me.

[Fryuni]

Ok
Since godoc is deprecated I'll close this one

Thanks

[thediveo]

The problem is that io.EOF works as an example, because io is a top-level package and thus already the full import path. http.Foo doesn't work, but needs to be net/http.Foo. Now for referencing a Symbol in another package of mine, I now need to fiddle around with full import paths as can be seen in this godoc 1.19 branch of one of my Go modules when trying to link to watcher.Watcher: https://github.com/thediveo/whalewatcher/blob/9b0e95100f263088e458a5f52b10bcc5902767be/doc.go#L26:

A [github.com/thediveo/whalewatcher/watcher.Watcher] watches the containers of a
single container engine instance when running its Watch method in a separate go
routine. Cancel its passed context to stop watching.

[seankhliao]

If you imported the package you would be able to reference it with the imported package name.
Otherwise just watcher is an unknown/ambiguous reference.