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

cmd/godoc: simplify documenting commands #3579

Closed
gopherbot opened this Issue Apr 30, 2012 · 6 comments

Comments

Projects
None yet
4 participants
@gopherbot
Copy link

gopherbot commented Apr 30, 2012

by axel.schreiner:

godoc binds GOPATH/src to /src/pkg;
i.e., directories below GOPATH/src contain packages, not commands;
i.e., HTTP requests for /cmd/FOO only work if FOO is in GOROOT/src/cmd.

Looks to me like godoc cannot readily document user-written commands outside GOROOT. (I
kludged this using -path; however, it's a very awkward, undocumented kludge.)

Note that the distributed directory structure is GOROOT/src/pkg for packages and
GOROOT/src/cmd for commands.

If godoc/main.go/main() were changed, e.g., to

    // Bind $GOPATH trees into Go root.
    for _, p := range filepath.SplitList(build.Default.GOPATH) {
        fs.Bind("/src/pkg", OS(p), "/src/pkg", bindAfter)
        fs.Bind("/src/cmd", OS(p), "/src/cmd", bindAfter)
    }

then HTTP requests /pkg/FOO and /cmd/FOO would document user packages in
GOPATH/src/pkg/FOO and commands in GOPATH/src/cmd/FOO, respectively. (This does,
however, break the current interpretation of GOPATH for godoc).

Alternatively,

    // Bind $GOPATH trees into Go root.
    for _, p := range filepath.SplitList(build.Default.GOPATH) {
        fs.Bind("/src/cmd", OS(p), "/src/cmd", bindAfter)
        fs.Bind("/src/pkg", OS(p), "/src", bindAfter)
    }

would not break the current interpretation of GOPATH and would also document user
commands. (The package list in this case shows a package 'cmd' containing directories
for user commands.)

The option -path only applies to packages because it binds each path /FOO/BAR to
/src/pkg/BAR,
i.e., an HTTP request /pkg/BAR will produce documentation from /FOO/BAR.

One could add another option -cmds to godoc/godoc.go/initHandlers() to bind paths to
/src/cmd to allow single user commands to be added to the server:

var ...
    cmdPath = flag.String("cmds", "", "additional command directories (colon-separated)")

initHandler...

    // Add named directories in -cmds argument as
    // subdirectories of src/cmd.
    for _, p := range filepath.SplitList(*cmdPath) {
        _, elem := filepath.Split(p)
        if elem == "" {
            log.Fatalf("invalid -cmds argument: %q has no final element", p)
        }
        fs.Bind("/src/cmd/"+elem, OS(p), "/", bindReplace)
    }

Which operating system are you using?
MacOS X 10.8

Which version are you using?  (run 'go version')
go1
@mewmew

This comment has been minimized.

Copy link
Contributor

mewmew commented Jun 8, 2012

Comment 1:

I don't think that the generation of command documentation should require a specific
path (i.e. $GOPATH/src/cmd/) to be used. Instead godoc should check if the package name
is equal to main, and if so generate command documentation. If the package name isn't
equal to main it should generate package documentation.
@rsc

This comment has been minimized.

Copy link
Contributor

rsc commented Sep 12, 2012

Comment 2:

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

Status changed to Accepted.

@rsc

This comment has been minimized.

Copy link
Contributor

rsc commented Sep 12, 2012

Comment 3:

Labels changed: added go1.1.

@rsc

This comment has been minimized.

Copy link
Contributor

rsc commented Dec 10, 2012

Comment 5:

Labels changed: added size-m.

@mewmew

This comment has been minimized.

Copy link
Contributor

mewmew commented Jan 21, 2013

Comment 6:

As far as I can tell, this issue is a duplicate of issue #3199.
@adg

This comment has been minimized.

Copy link
Contributor

adg commented Mar 8, 2013

Comment 7:

I am inclined to agree.

Status changed to Duplicate.

Merged into issue #3199.

@rsc rsc added this to the Go1.1 milestone Apr 14, 2015

@rsc rsc removed the go1.1 label Apr 14, 2015

@golang golang locked and limited conversation to collaborators Jun 24, 2016

This issue was closed.

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.