Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

x/tools/cmd/godoc: handle file name arguments better, particularly w.r.t. GOPATH #4330

Closed
robpike opened this issue Nov 1, 2012 · 18 comments

Comments

@robpike
Copy link
Contributor

robpike commented Nov 1, 2012

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/"

%
@rsc
Copy link
Contributor

rsc commented Nov 1, 2012

Comment 1:

The argument to godoc is an import path, not a directory name.

@robpike
Copy link
Contributor Author

robpike commented Nov 1, 2012

Comment 2:

And that constantly confuses, because it's location sensitive. It's a fine answer but it
shouldn't be the only answer. A file-based argument makes a lot of sense as a fallback
if not as the primary.

@adg
Copy link
Contributor

adg commented Jan 29, 2013

Comment 3:

Owner changed to @adg.

@adg
Copy link
Contributor

adg commented Jan 29, 2013

Comment 4:

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
Copy link
Contributor

rsc commented Jan 31, 2013

Comment 5:

Your description sounds right to me.

@rsc
Copy link
Contributor

rsc commented Jan 31, 2013

Comment 6:

Labels changed: added priority-later, removed priority-soon.

@dominikh
Copy link
Member

dominikh commented Mar 6, 2013

Comment 7:

One might want to document this spec so that 3rd party tools can adhere to it as well.

@rsc
Copy link
Contributor

rsc commented Mar 12, 2013

Comment 8:

Labels changed: added go1.1maybe, removed go1.1.

@adg
Copy link
Contributor

adg commented Mar 18, 2013

Comment 9:

Labels changed: added godoc.

@robpike
Copy link
Contributor Author

robpike commented May 18, 2013

Comment 10:

Labels changed: added go1.2maybe, removed go1.1maybe.

@rsc
Copy link
Contributor

rsc commented Jul 30, 2013

Comment 11:

Labels changed: added feature.

@robpike
Copy link
Contributor Author

robpike commented Aug 19, 2013

Comment 12:

Would love to see this happen as part of the new godoc.

@robpike
Copy link
Contributor Author

robpike commented Aug 29, 2013

Comment 13:

Won't happen for 1.2, though.

Labels changed: removed go1.2maybe.

@rsc
Copy link
Contributor

rsc commented Nov 27, 2013

Comment 14:

Labels changed: added go1.3maybe.

@rsc
Copy link
Contributor

rsc commented Nov 27, 2013

Comment 15:

Labels changed: removed feature.

@rsc
Copy link
Contributor

rsc commented Dec 4, 2013

Comment 16:

Labels changed: added release-none, removed go1.3maybe.

@rsc
Copy link
Contributor

rsc commented Dec 4, 2013

Comment 17:

Labels changed: added repo-tools.

@rsc rsc added this to the Unplanned milestone Apr 10, 2015
@rsc rsc changed the title cmd/godoc: handle file name arguments better, particularly w.r.t. GOPATH x/tools/cmd/godoc: handle file name arguments better, particularly w.r.t. GOPATH Apr 14, 2015
@rsc rsc removed the repo-tools label Apr 14, 2015
@adg
Copy link
Contributor

adg commented May 27, 2016

Now that we have go doc I don't think this is worth addressing.

@adg adg closed this as completed May 27, 2016
@golang golang locked and limited conversation to collaborators May 27, 2017
@rsc rsc unassigned adg Jun 22, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

5 participants