x/tools/cmd/godoc: handle file name arguments better, particularly w.r.t. GOPATH #4330
Labels
Milestone
Comments
|
Owner changed to @adg. |
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? |
rsc
changed the title
|
Now that we have |
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
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/" %The text was updated successfully, but these errors were encountered: