Join GitHub today
GitHub is home to over 36 million developers working together to host and review code, manage projects, and build software together.Sign up
x/tools/cmd/godoc: handle file name arguments better, particularly w.r.t. GOPATH #4330
Summary: If a package is present on GOPATH, godoc should find it, perhaps only after failing to find it in GOROOT. I believe there are a number of related problems here, hard to tease out. The exact meaning of the arguments to godoc is not well documented, which is part of it. But the key point is that godoc is too aggressive about resolving those "names" inside $GOROOT even if $GOPATH is set, or even if it's not. On the command line at least, godoc seems to disregard GOPATH completely. Example (Ignore the fact my documentation is missing and just observe how godoc behaves): % cd % echo $GOROOT /Users/r/go % echo $GOPATH /Users/r % % cd rspace.cmd /Users/r/src/code.google.com/p/rspace.cmd # IN GOPATH % ls AUTHORS LICENSE codereview.cfg now typo CONTRIBUTORS README freq translate unicode % godoc now # WHY DOESN'T THIS WORK? 2012/11/01 12:52:06 open /Users/r/go/src/pkg/now: no such file or directory # TRUE BUT "now" EXISTS IN THIS DIRECTORY AND/OR ON GOPATH % godoc ./now # THIS DOES WORK, BUT IS FUSSY. PACKAGE package main import "./now" tubenose=% godoc ./unicode PACKAGE package main import "./unicode" % cd # BACK HOME % godoc now 2012/11/01 12:53:57 open /Users/r/go/src/pkg/now: no such file or directory # WHAT ABOUT GOPATH? tubenose=% godoc /Users/r/src/code.google.com/p/rspace.cmd/now/ # GIVE FULL PATH AND IT WORKS PACKAGE package main import "/Users/r/src/code.google.com/p/rspace.cmd/now/" %
Let's spec out how the godoc command-line should work: Godoc's first non-flag argument must be one of: 1. a package import path (treated as relative to $GOROOT/src/pkg or $GOPATH/src) 2a. a command name (treated as relative to $GOROOT/src/cmd) 2b. a command name prefixed with "cmd/" (treated as relative to $GOROOT/src) 3. a relative path to a package or command (may or may not be inside $GOROOT or $GOPATH) In each of these cases, we know what to display: 1. docs for the first package found by go/build 2a. docs for the command; if there is a conflict between the command name and an import path (1) then the import path is matched first, and a warning is printed to use "godoc cmd/foo" for docs on command foo. 2b. docs for the command. 3. docs for the package or command found at that path The missing piece that is confusing Rob here is that "foo" is not equivalent to "./foo". I changed this in golang.org/cl/7132044, but Russ took issue with the change, and we settled on providing a warning if "godoc foo" is issued and the directory ./foo exists. Any opinions?