x/tools/cmd/godoc: remove CLI support in Go 1.12

[bradfitz]

Now that we have the cmd/go "go doc" CLI for getting documentation, does it make sense for x/tools/cmd/godoc to also have CLI support?

I propose we delete x/tools/cmd/godoc's CLI support and keep it being a web-only tool. Users who want CLI support can use "go doc". Both are shipped with Go releases.

/cc @dsnet @andybons @stamblerre @shantuo @robpike

[bradfitz]

As background, this is motivated by the Go team maintaining something like 5 variations of "godoc" tools at the moment, and there's too much duplication and maintenance effort.

[bradfitz]

As background, this is motivated by the Go team maintaining something like 5 variations of "godoc" tools at the moment, and there's too much duplication and maintenance effort.

[bradfitz]

@ianthehat mentioned that many IDEs invoke the godoc binary from releases to get documentation. Which ones? Can we convert them to use "go doc"?

[bradfitz]

@ianthehat mentioned that many IDEs invoke the godoc binary from releases to get documentation. Which ones? Can we convert them to use "go doc"?

[bradfitz]

Or for such IDEs, it was proposed that we could perhaps make the "godoc" binary detect when it's in "legacy CLI mode" and invoke the "go doc" command as a subcommand instead?

[bradfitz]

Or for such IDEs, it was proposed that we could perhaps make the "godoc" binary detect when it's in "legacy CLI mode" and invoke the "go doc" command as a subcommand instead?

[agnivade]

As one such example - #16183 needs a fix to both godoc and go doc.

[agnivade]

As one such example - #16183 needs a fix to both godoc and go doc.

[rsc]

@ianthehat, the IDE issue just means we have to coordinate this over multiple releases if we do it. If we decide to do it, then we can work on making it smooth. Personally I'm +1 on simplifying so that "godoc" is always just the package web server and not also the main web site nor a command-line doc viewer.

It also might be better to just drop the name "godoc" entirely, to avoid confusion with "go doc" and also godoc.org. The web server could be godochttp/godocsrv/godocweb/etc.

[rsc]

@ianthehat, the IDE issue just means we have to coordinate this over multiple releases if we do it. If we decide to do it, then we can work on making it smooth. Personally I'm +1 on simplifying so that "godoc" is always just the package web server and not also the main web site nor a command-line doc viewer.

It also might be better to just drop the name "godoc" entirely, to avoid confusion with "go doc" and also godoc.org. The web server could be godochttp/godocsrv/godocweb/etc.

[mpx]

A single CLI documentation tool would be good.

godoc has some useful functionality that isn't present in go doc. Eg, output of full package documentation (#25595). I'd be in favour of adding this to go doc as an option.

Another example might be HTML output from godoc. This probably isn't a good fit for go doc. Maybe godoc could continue to have a cut-down mode that only outputs full package doc in HTML? I don't have any strong opinions here (I don't use it), but others might.

[mpx]

A single CLI documentation tool would be good.

godoc has some useful functionality that isn't present in go doc. Eg, output of full package documentation (#25595). I'd be in favour of adding this to go doc as an option.

Another example might be HTML output from godoc. This probably isn't a good fit for go doc. Maybe godoc could continue to have a cut-down mode that only outputs full package doc in HTML? I don't have any strong opinions here (I don't use it), but others might.

[bradfitz]

Decision: we'll document in the Go 1.11 release notes that the Go 1.11 release will be the last to support CLI mode godoc (no space). In Go 1.12, users (and any IDEs?) will need to use go doc for the CLI mode.

[bradfitz]

Decision: we'll document in the Go 1.11 release notes that the Go 1.11 release will be the last to support CLI mode godoc (no space). In Go 1.12, users (and any IDEs?) will need to use go doc for the CLI mode.

[gopherbot]

Change https://golang.org/cl/126737 mentions this issue: doc/go1.11: add note to remove CLI support for godoc

[gopherbot]

Change https://golang.org/cl/126737 mentions this issue: doc/go1.11: add note to remove CLI support for godoc

[gopherbot]

Change https://golang.org/cl/141397 mentions this issue: godoc, cmd/godoc: remove CLI support

[gopherbot]

Change https://golang.org/cl/141397 mentions this issue: godoc, cmd/godoc: remove CLI support

[adg]

What about @rsc's suggestion that we rename the godoc command to something else? I'm on the fence. I guess we could see if anyone gets confused first.

[adg]

What about @rsc's suggestion that we rename the godoc command to something else? I'm on the fence. I guess we could see if anyone gets confused first.

[bradfitz]

@adg, I'm fine renaming it (assuming we find a good name) but I didn't want to do it in that CL.

I'd also rather push that decision out until the website rearchitecting plan is more solidified. I haven't heard the latest plan there in some time.

[bradfitz]

@adg, I'm fine renaming it (assuming we find a good name) but I didn't want to do it in that CL.

I'd also rather push that decision out until the website rearchitecting plan is more solidified. I haven't heard the latest plan there in some time.

[adg]

Sounds good.

[adg]

Sounds good.

[myitcv]

Picking up on discussion with @adg in the CL.

I think this change being merged now will create a problem, per @ianthehat's comments, for VSCode (at least) which has a default of godoc. On the last golang-tools call, @ramya-rao-a mentioned that VSCode currently uses godoc by default, with the option of gogetdoc (which is what I think we see here).

I read https://golang.org/doc/go1.11#godoc as "godoc as a CLI will be around, but deprecated, for Go 1.11, and then not available in Go 1.12".

Given godoc is installed from x/tools, does this not break things pre Go 1.12?

[myitcv]

Picking up on discussion with @adg in the CL.

I think this change being merged now will create a problem, per @ianthehat's comments, for VSCode (at least) which has a default of godoc. On the last golang-tools call, @ramya-rao-a mentioned that VSCode currently uses godoc by default, with the option of gogetdoc (which is what I think we see here).

I read https://golang.org/doc/go1.11#godoc as "godoc as a CLI will be around, but deprecated, for Go 1.11, and then not available in Go 1.12".

Given godoc is installed from x/tools, does this not break things pre Go 1.12?

[agnivade]

I think one should use the godoc which is packaged as a part of the 1.11 distribution. If you compile godoc from HEAD, it has to break some time or other.

The release notes are correct assuming one uses godoc from the distribution. Not if someone builds from master.

[agnivade]

I think one should use the godoc which is packaged as a part of the 1.11 distribution. If you compile godoc from HEAD, it has to break some time or other.

The release notes are correct assuming one uses godoc from the distribution. Not if someone builds from master.

[bradfitz]

What @agnivade said.

[bradfitz]

What @agnivade said.

[myitcv]

@agnivade @bradfitz - that makes sense.

Will just wait for @ramya-rao-a to confirm which godoc VSCode is currently using.

[myitcv]

@agnivade @bradfitz - that makes sense.

Will just wait for @ramya-rao-a to confirm which godoc VSCode is currently using.

[ramya-rao-a]

@myitcv is right. godoc cli is used in VS Code. We install it using go get golang.org/x/tools/cmd/godoc

I would be ok to move to using go doc instead.

[ramya-rao-a]

@myitcv is right. godoc cli is used in VS Code. We install it using go get golang.org/x/tools/cmd/godoc

I would be ok to move to using go doc instead.

[myitcv]

@ramya-rao-a per #25443 (comment) you could also use godoc found at $GOROOT/bin/godoc.

The more immediate question: is vscode-go's "default" install currently broken because golang.org/x/tools/cmd/godoc has lost its CLI powers?

[myitcv]

@ramya-rao-a per #25443 (comment) you could also use godoc found at $GOROOT/bin/godoc.

The more immediate question: is vscode-go's "default" install currently broken because golang.org/x/tools/cmd/godoc has lost its CLI powers?

[ramya-rao-a]

Pardon my ignorance, I have some basic questions...

I think one should use the godoc which is packaged as a part of the 1.11 distribution. If you compile godoc from HEAD, it has to break some time or other

• Was godoc always packaged as part of the Go distribution (and so available at GOROOT/bin)? If I were to remove the "get godoc from golang.org/x/tools/cmd/godoc" step in VS Code, and rely on GOROOT/bin/godoc binary, would this work for all previous versions of Go?
• Is there any difference between the godoc packaged as part of the Go distribution and the one compiled from golang.org/x/tools/cmd/godoc apart from the fact that the latter will be using the HEAD?
• If I understand this correctly, from Go 1.12 onwards, godoc will no longer be packaged as part of the Go distribution and editors should use go doc instead?

[ramya-rao-a]

Pardon my ignorance, I have some basic questions...

I think one should use the godoc which is packaged as a part of the 1.11 distribution. If you compile godoc from HEAD, it has to break some time or other

• Was godoc always packaged as part of the Go distribution (and so available at GOROOT/bin)? If I were to remove the "get godoc from golang.org/x/tools/cmd/godoc" step in VS Code, and rely on GOROOT/bin/godoc binary, would this work for all previous versions of Go?
• Is there any difference between the godoc packaged as part of the Go distribution and the one compiled from golang.org/x/tools/cmd/godoc apart from the fact that the latter will be using the HEAD?
• If I understand this correctly, from Go 1.12 onwards, godoc will no longer be packaged as part of the Go distribution and editors should use go doc instead?

[bradfitz]

Was godoc always packaged as part of the Go distribution (and so available at GOROOT/bin)? If I were to remove the "get godoc from golang.org/x/tools/cmd/godoc" step in VS Code, and rely on GOROOT/bin/godoc binary, would this work for all previous versions of Go?

Yes.

Is there any difference between the godoc packaged as part of the Go distribution and the one compiled from golang.org/x/tools/cmd/godoc

Nope.

If I understand this correctly, from Go 1.12 onwards, godoc will no longer be packaged as part of the Go distribution and editors should use go doc instead?

I'm not sure that's been decided, but it's likely. But if we do ship godoc, it won't have CLI mode, and it might even be named something else.

[bradfitz]

Was godoc always packaged as part of the Go distribution (and so available at GOROOT/bin)? If I were to remove the "get godoc from golang.org/x/tools/cmd/godoc" step in VS Code, and rely on GOROOT/bin/godoc binary, would this work for all previous versions of Go?

Yes.

Is there any difference between the godoc packaged as part of the Go distribution and the one compiled from golang.org/x/tools/cmd/godoc

Nope.

If I understand this correctly, from Go 1.12 onwards, godoc will no longer be packaged as part of the Go distribution and editors should use go doc instead?

I'm not sure that's been decided, but it's likely. But if we do ship godoc, it won't have CLI mode, and it might even be named something else.

[ramya-rao-a]

Thanks @bradfitz In that case, I can make the change to remove the dependency on golang.org/x/tools/cmd/godoc for the next version of the Go plugin in VS Code and fallback on the GOROOT/bin/godoc. And in the long run, I can look into using go doc instead.

@myitcv

The more immediate question: is vscode-go's "default" install currently broken because golang.org/x/tools/cmd/godoc has lost its CLI powers

I just tried go get golang.org/x/tools/cmd/godoc and the CLI mode works just fine. Is there a timeline when we can expect the godoc generated from running go get golang.org/x/tools/cmd/godoc to stop having the CLI mode?

[ramya-rao-a]

Thanks @bradfitz In that case, I can make the change to remove the dependency on golang.org/x/tools/cmd/godoc for the next version of the Go plugin in VS Code and fallback on the GOROOT/bin/godoc. And in the long run, I can look into using go doc instead.

@myitcv

The more immediate question: is vscode-go's "default" install currently broken because golang.org/x/tools/cmd/godoc has lost its CLI powers

I just tried go get golang.org/x/tools/cmd/godoc and the CLI mode works just fine. Is there a timeline when we can expect the godoc generated from running go get golang.org/x/tools/cmd/godoc to stop having the CLI mode?

[myitcv]

@ramya-rao-a - per our Slack conversation, I suspect that worked because you already have golang.org/x/tools/cmd/godoc checked out in your GOPATH. The changes to remove the CLI support are already merged, hence a fresh install (or after a go get -u golang.org/x/tools/cmd/godoc):

export GOPATH=$(mktemp -d)
cd $GOPATH
go get golang.org/x/tools/cmd/godoc
$GOPATH/bin/godoc strings

gives:

Unexpected arguments.
usage: godoc -http=localhost:6060
  -analysis string
        comma-separated list of analyses to perform (supported: type, pointer). See http://golang.org/lib/godoc/analysis/help.html
...

with a non-zero exit code.

[myitcv]

@ramya-rao-a - per our Slack conversation, I suspect that worked because you already have golang.org/x/tools/cmd/godoc checked out in your GOPATH. The changes to remove the CLI support are already merged, hence a fresh install (or after a go get -u golang.org/x/tools/cmd/godoc):

export GOPATH=$(mktemp -d)
cd $GOPATH
go get golang.org/x/tools/cmd/godoc
$GOPATH/bin/godoc strings

gives:

Unexpected arguments.
usage: godoc -http=localhost:6060
  -analysis string
        comma-separated list of analyses to perform (supported: type, pointer). See http://golang.org/lib/godoc/analysis/help.html
...

with a non-zero exit code.

[ramya-rao-a]

In that case, anybody setting up VS Code from scratch will not get the documentation on hover feature until I release an update. That should be fine.

[ramya-rao-a]

In that case, anybody setting up VS Code from scratch will not get the documentation on hover feature until I release an update. That should be fine.

[gopherbot]

Change https://golang.org/cl/141717 mentions this issue: cmd/godoc: synchronously init corpus for index mode

[gopherbot]

Change https://golang.org/cl/141717 mentions this issue: cmd/godoc: synchronously init corpus for index mode