x/tools/cmd/godoc: corpus fstree is nil

[jsumners]

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

$ go version
go version go1.20.2 darwin/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="/Users/jsumners/Library/Caches/go-build"
GOENV="/Users/jsumners/Library/Application Support/go/env"
GOEXE=""
GOEXPERIMENT=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="darwin"
GOINSECURE=""
GOMODCACHE="/Users/jsumners/go/pkg/mod"
GONOPROXY=""
GONOSUMDB=""
GOOS="darwin"
GOPATH="/Users/jsumners/go"
GOPRIVATE=""
GOPROXY="https://proxy.golang.org,direct"
GOROOT="/Users/jsumners/.go"
GOSUMDB="sum.golang.org"
GOTMPDIR=""
GOTOOLDIR="/Users/jsumners/.go/pkg/tool/darwin_amd64"
GOVCS=""
GOVERSION="go1.20.2"
GCCGO="gccgo"
GOAMD64="v1"
AR="ar"
CC="clang"
CXX="clang++"
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 -arch x86_64 -m64 -pthread -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -fdebug-prefix-map=/var/folders/qg/tsbwrf9s249bmgw48nhygzkh0000gn/T/go-build947610718=/tmp/go-build -gno-record-gcc-switches -fno-common"

What did you do?

1. Start a new project and add some documentation
2. go install golang.org/x/tools/cmd/godoc@latest
3. godoc -http :3000 to preview the documentation

What did you expect to see?

A working documentation server so that I could verify that the docs I am writing appear as I intend them to.

What did you see instead?

❯ godoc -http :3000
using module mode; GOMOD=/Users/jsumners/Projects/go-reggie/go.mod
2023/04/04 10:21:30 godoc: corpus fstree is nil

---

Research indicates that this is some problem with godoc not resolving symlinks. I use https://github.com/stefanmaric/g to manage my Go installs. So my GOROOT looks like:

❯ ls -lt $GOROOT
total 0
lrwxr-xr-x  1 jsumners  staff  41 Mar 22 08:58 test -> /Users/jsumners/.go/.versions/1.20.2/test
lrwxr-xr-x  1 jsumners  staff  40 Mar 22 08:58 src -> /Users/jsumners/.go/.versions/1.20.2/src
lrwxr-xr-x  1 jsumners  staff  40 Mar 22 08:58 pkg -> /Users/jsumners/.go/.versions/1.20.2/pkg
lrwxr-xr-x  1 jsumners  staff  41 Mar 22 08:58 misc -> /Users/jsumners/.go/.versions/1.20.2/misc
lrwxr-xr-x  1 jsumners  staff  40 Mar 22 08:58 lib -> /Users/jsumners/.go/.versions/1.20.2/lib
lrwxr-xr-x  1 jsumners  staff  40 Mar 22 08:58 doc -> /Users/jsumners/.go/.versions/1.20.2/doc
lrwxr-xr-x  1 jsumners  staff  51 Mar 22 08:58 codereview.cfg -> /Users/jsumners/.go/.versions/1.20.2/codereview.cfg
lrwxr-xr-x  1 jsumners  staff  40 Mar 22 08:58 bin -> /Users/jsumners/.go/.versions/1.20.2/bin
lrwxr-xr-x  1 jsumners  staff  40 Mar 22 08:58 api -> /Users/jsumners/.go/.versions/1.20.2/api
lrwxr-xr-x  1 jsumners  staff  44 Mar 22 08:58 VERSION -> /Users/jsumners/.go/.versions/1.20.2/VERSION
lrwxr-xr-x  1 jsumners  staff  48 Mar 22 08:58 SECURITY.md -> /Users/jsumners/.go/.versions/1.20.2/SECURITY.md
lrwxr-xr-x  1 jsumners  staff  46 Mar 22 08:58 README.md -> /Users/jsumners/.go/.versions/1.20.2/README.md
lrwxr-xr-x  1 jsumners  staff  44 Mar 22 08:58 PATENTS -> /Users/jsumners/.go/.versions/1.20.2/PATENTS
lrwxr-xr-x  1 jsumners  staff  44 Mar 22 08:58 LICENSE -> /Users/jsumners/.go/.versions/1.20.2/LICENSE
lrwxr-xr-x  1 jsumners  staff  52 Mar 22 08:58 CONTRIBUTING.md -> /Users/jsumners/.go/.versions/1.20.2/CONTRIBUTING.md
lrwxr-xr-x  1 jsumners  staff  49 Feb  2 09:19 CONTRIBUTORS -> /Users/jsumners/.go/.versions/1.19.4/CONTRIBUTORS

I expect that such an install is not uncommon. It seems to me that the godoc util should resolve symlinks.

[mknyszek]

CC @golang/tools-team

[findleyr]

x/tools/cmd/godoc is deprecated. Can you please try https://pkg.go.dev/golang.org/x/pkgsite/cmd/pkgsite to see if it resolves your problem?

[jsumners]

x/tools/cmd/godoc is deprecated. Can you please try https://pkg.go.dev/golang.org/x/pkgsite/cmd/pkgsite to see if it resolves your problem?

Yes, this one works. Is the intention to rename it to godoc? I was using that because it's what all of the resources I found suggested to use.

[jsumners]

For what it's worth, I expected some incantation of go doc to do the work. I had to search to learn that it was a separate install of godoc (no space) to accomplish the task.

[findleyr]

@jsumners unfortunately there is a long history of confusion regarding godoc, go doc, x/tools/cmd/godoc, godoc.org, and go/doc.

This is one of the reasons we decided not to call pkgsite godoc!

[jsumners]

As a neophyte Go person, I'd suggest making it easier instead of more complicated. As I mentioned, I expected this functionality in go doc as it already dumps the docs in question to the terminal when run in the project root.

I can tell you that I would never recognize pkgsite as the solution, or even anything related to docs, just by the tool name and without being told "this is what you need".

[findleyr]

@jsumners thanks for that feedback. You are right that there is a discoverability problem.

[nixoncode]

I got the solution on an old issue #15049

#15049 (comment)

    godoc -http=:6060 -goroot /usr/share/go

[seankhliao]

The godoc command was deprecated.

[jsumners]

That may be, but re-read the thread: the current state is not obvious.

[seankhliao]

see #68106