cmd/doc: confusing error message when directory only contains test package

[mark-rushakoff]

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

$ go version
go version go1.12.5 darwin/amd64
$ gotip version
go version devel +a9e107c85c Tue May 14 16:36:38 2019 +0000 darwin/amd64

Does this issue reproduce with the latest release?

Yes, but I haven't tested with go 1.11 to see if this was a 1.12 regression.

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

go env Output

$ go env
go env
GOARCH="amd64"
GOBIN=""
GOCACHE="/Users/mr/Library/Caches/go-build"
GOEXE=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="darwin"
GOOS="darwin"
GOPATH="/Users/mr/go"
GOPROXY=""
GORACE=""
GOROOT="/usr/local/Cellar/go/1.12.5/libexec"
GOTMPDIR=""
GOTOOLDIR="/usr/local/Cellar/go/1.12.5/libexec/pkg/tool/darwin_amd64"
GCCGO="gccgo"
CC="clang"
CXX="clang++"
CGO_ENABLED="1"
GOMOD="/tmp/fff/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 -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -fdebug-prefix-map=/var/folders/ct/bl4_z3g51ks8239_r2k07v_40000gn/T/go-build494795842=/tmp/go-build -gno-record-gcc-switches -fno-common"

What did you do?

I created a module that only had an example test file:

bash-3.2$ tree .
.
├── example_test.go
└── go.mod

0 directories, 2 files
bash-3.2$ cat go.mod
module z

go 1.12
bash-3.2$ cat example_test.go
package z_test

import "testing"

func Example(t *testing.T) {
}

And then I ran go doc .

What did you expect to see?

A clear error message, maybe like when there are no Go files: doc: no such package /tmp/z.

What did you see instead?

A confusing error message: doc: multiple packages in directory /tmp/z.

When I originally ran into this, in my non-trivial example, I was confused. Multiple packages? Did I misname my test package? Did I accidentally have two different source packages due to a typo in the package directive?

I would suggest something like doc: no non-test packages in directory /tmp/z so that it's clear that doc would have worked if I had any non-test files in the directory.

[agnivade]

Ha ! The code meant to ensure that there is only 1 package it processes. But the check is incorrect :)

if len(pkgs) != 1 {
	log.Fatalf("multiple packages in directory %s", pkg.Dir)
}

Will send a CL.

[gopherbot]

Change https://golang.org/cl/178878 mentions this issue: cmd/doc: display a proper error when no packages are found