Open mvdan opened 1 year ago
Doesn't seem like much of a problem to me. The output is helpful, arguably more so than the others'. I wouldn't call it "broken".
Is vet problematic for you too? Because it's also different, and harmlessly so.
At a minimum, the exit status 2
seems wrong.
I wouldn't mind if go doc -h
resembled go vet -h
. But I do think we want to be consistent for the sake of not confusing our users. I don't claim that one way is better than the other, but go doc -h
is the outlier today.
I was just stumped at go doc -h
hanging for multiple seconds when my current directory was a Go package with a large tree of dependencies. I thought to myself that perhaps it was loading the entire package tree and filling the build cache, which would certainly be a bug.
Here's a small repro, using https://github.com/mvdan/sh/tree/master/interp as a sample Go package inside a third party module with some imports:
$ go clean -cache -modcache
$ time go doc -h
[...]
real 0m0.348s
user 0m0.069s
sys 0m0.020s
$ go clean -cache -modcache
$ time go help doc
[...]
real 0m0.005s
user 0m0.007s
sys 0m0.000s
In this particular case, the wait was about a third of a second, because the package and its dependencies are smaller - go list -deps
shows 63 packages. With the larger package, where go doc -h
with an empty cache took a staggering 17s, go list -deps
shows 627 packages.
I wouldn't mind if
go doc -h
resembledgo vet -h
. But I do think we want to be consistent for the sake of not confusing our users. I don't claim that one way is better than the other, butgo doc -h
is the outlier today.
I'm not sure which way is best, but thought I'd share my experience. I hadn't noticed the usage()
part of doc
recently when writing a change (not having considered someone running go doc -h
), and just focused on updating the documentation in src/cmd/go/internal/doc/doc.go
. In my case it wouldn't have made any difference, but having duplicated documentation in different places does increase the chance of documentation differing in different places.
One alternative option would be to grab some documentation (perhaps just the UsageLine
straight from the base.Command
defined in src/cmd/go/internal/doc/doc.go
.
Consistency between tools would be nice, but I'd lean towards making the others at least print their basic usage, rather than just essentially remove -h
from all tools.
I was just stumped at
go doc -h
hanging for multiple seconds when my current directory was a Go package with a large tree of dependencies. I thought to myself that perhaps it was loading the entire package tree and filling the build cache, which would certainly be a bug.
That looks to be because dirsInit()
is called before the flag parsing. From a brief read of the code it looks like it could be started after flag parsing (though the extras would need to be passed to do()
in order for the tests to be set up appropriately), which would solve your particular case of go doc -h
being too slow.
For the wider issue of initial go doc
running being slow from a package with many dependencies, you'd know better than me but I'd imagine that deserves a separate issue.
In general,
go command -h
is very short at just a few lines, pointing instead togo help command
for the longer help text. However,go doc -h
is an outlier.Note that
go doc -h
prints many more lines than the others, but also, it prints anexit status 2
line which seems wrong. The latter seems to be because it combinesCustomFlags: true
with executinggo tool doc -h
, which means that the flag parsing happens in the child process, and the parent process simply shows the non-zero exit status.We probably should:
go doc -h
to show a few lines like the others, for consistencygo doc
to never showexit status 2
for flag errors likego doc -h
orgo doc -badflag
Also note that
go tool doc -h
is slightly confusing; unlike others such asgo tool fix -h
, it shows the help forgo doc
rather thango tool doc
.cc @robpike @bcmills @matloob