Go: 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]

@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?

[agnivade]

As one such example - https://github.com/golang/go/issues/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.

[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.

[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

[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.

[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?

[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.

[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.

[myitcv]

@ramya-rao-a per https://github.com/golang/go/issues/25443#issuecomment-428844018 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?

[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?

[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.

[gopherbot]

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

[gopherbot]

Change https://golang.org/cl/145222 mentions this issue: doc: replace command line usages of godoc with go doc

[gopherbot]

Change https://golang.org/cl/162982 mentions this issue: godoc: remove unused CLI-only identifiers

[gopherbot]

Change https://golang.org/cl/162984 mentions this issue: cmd/godoc: re-add documentation for flat presentation mode

[leucos]

Is there any way to generate HTML documentation like we could do with godoc ./package --html before 1.12 ? It seem that go doc has no provision for HTML output.

Currently resorting to this workaround

[dmitshur]

@leucos You should be able to continue to use the -url flag of the godoc binary for that purpose.

$ godoc -help 2>&1 | grep -C 1 'url'
        show timestamps with directory listings
  -url string
        print HTML for named URL

$ godoc -url /pkg/go/format
<HTML documentation for package go/format>

[leucos]

Great, thanks @dmitshur , works like a charm. Sorry for the noise on a closed topic.

[trivigy]

@dmitshur Any suggestions as to how to do that when working with a local go module based development? I got godoc -html=:6060 to work but since my packages are on modules and not part of the GOPATH godoc is not listing them in the generated html.

[dmitshur]

@trivigy The godoc command does not have support for module mode yet, but work on resolving that is underway. The umbrella issue #26827 is tracking that task, and you can subscribe to it for further updates.

[gopherbot]

Change https://golang.org/cl/172975 mentions this issue: godoc: declare small victory over the punched card tyranny

[gopherbot]

Change https://golang.org/cl/177737 mentions this issue: godoc: re-add test for ignoring //line comments in source code

[gingerhot]

Before v1.12, I can use godoc -html <a relative path not in GOPATH> to generate godoc output to a specified path, but now I don't know how to achieve this. I think there should be an equivalent go doc -html as well.

Otherwise where is the Go claimed backward compatibility?

[bradfitz]

Otherwise where is the Go claimed backward compatibility?

The Go compatibility promise excludes tools: https://golang.org/doc/go1compat#tools

[gingerhot]

@bradfitz thanks for your reply and clarifying of it. I misunderstood it.

But I still hope there's a such go doc -html subcommand option.

[dmitshur]

Before v1.12, I can use godoc -html <a relative path not in GOPATH> to generate godoc output to a specified path, but now I don't know how to achieve this.

@gingerhot Have you considered the godoc -url flag? It can be used to achieve very similar results. See a comment above.

[gingerhot]

@dmitshur Thank you for response. I've read your solution above, it's awesome for those packages within the GOPATH, I need do some tricks to make it work for those packages outside the GOPATH in my situation. Such as put the code under a src folder and set an adhoc GOPATH env before the command, but it does work. Thanks again.

[gopherbot]

Change https://golang.org/cl/197721 mentions this issue: cmd/golangorg: re-add documentation for flat presentation mode