x/tools/go/packages: docs for Config.Mode exception buried in LoadMode docs rather than Load

[myitcv]

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

$ go version
go version devel +59bfc18e34 Fri Jan 8 22:55:41 2021 +0000 linux/amd64
$ go list -m golang.org/x/tools
golang.org/x/tools v0.1.0

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/myitcv/.cache/go-build"
GOENV="/home/myitcv/.config/go/env"
GOEXE=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOINSECURE=""
GOMODCACHE="/home/myitcv/gostuff/pkg/mod"
GONOPROXY=""
GONOSUMDB=""
GOOS="linux"
GOPATH="/home/myitcv/gostuff"
GOPRIVATE=""
GOPROXY="https://proxy.golang.org,direct"
GOROOT="/home/myitcv/gos"
GOSUMDB="sum.golang.org"
GOTMPDIR=""
GOTOOLDIR="/home/myitcv/gos/pkg/tool/linux_amd64"
GOVCS=""
GOVERSION="devel +59bfc18e34 Fri Jan 8 22:55:41 2021 +0000"
GCCGO="gccgo"
AR="ar"
CC="gcc"
CXX="g++"
CGO_ENABLED="1"
GOMOD="/home/myitcv/gostuff/src/golang.org/x/tools/go.mod"
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-build2146745201=/tmp/go-build -gno-record-gcc-switches"

What did you do?

The docs for go/packages.Load state:

Config specifies loading options; nil behaves the same as an empty Config.

However, this fails to call out the exception to this rule which is somewhat buried in the docs for go/packages.LoadMode:

The zero value is a special case, equivalent to combining the NeedName, NeedFiles, and NeedCompiledGoFiles bits. ID and Errors (if present) will always be filled.

Indeed I think that exception is in the wrong place: it should be located in the docs for go/packages.Load, because it doesn't make any sense in the context of the docs for either the type or the constant values of that type.

Unless I'm missing something?

cc @matloob

[gopherbot]

Change https://go.dev/cl/588141 mentions this issue: go/packages: document fields that are part of JSON schema