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: remove CLI support in Go 1.12 #25443

Closed
bradfitz opened this issue May 17, 2018 · 34 comments

Comments

Projects
None yet
@bradfitz
Copy link
Member

commented May 17, 2018

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

@gopherbot gopherbot added this to the Proposal milestone May 17, 2018

@gopherbot gopherbot added the Proposal label May 17, 2018

@bradfitz

This comment has been minimized.

Copy link
Member Author

commented May 17, 2018

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

This comment has been minimized.

Copy link
Member Author

commented May 17, 2018

@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

This comment has been minimized.

Copy link
Member Author

commented May 17, 2018

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

This comment has been minimized.

Copy link
Member

commented May 17, 2018

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

@rsc

This comment has been minimized.

Copy link
Contributor

commented May 21, 2018

@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

This comment has been minimized.

Copy link
Contributor

commented May 27, 2018

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

This comment has been minimized.

Copy link
Member Author

commented Jul 16, 2018

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 bradfitz modified the milestones: Proposal, Go1.11 Jul 16, 2018

@bradfitz bradfitz changed the title proposal: x/tools/cmd/godoc: remove CLI support? x/tools/cmd/godoc: remove CLI support in Go 1.12 Jul 16, 2018

@bradfitz bradfitz self-assigned this Jul 16, 2018

@gopherbot

This comment has been minimized.

Copy link

commented Jul 31, 2018

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

@bradfitz bradfitz removed the Documentation label Jul 31, 2018

@bradfitz bradfitz modified the milestones: Go1.11, Go1.12 Jul 31, 2018

gopherbot pushed a commit that referenced this issue Jul 31, 2018

doc/go1.11: add note to remove CLI support for godoc
Updates #25443

Change-Id: I5e2f84f3cee6582807b2756ffac91e8583a2baec
Reviewed-on: https://go-review.googlesource.com/126737
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

jeet-parekh added a commit to jeet-parekh/go that referenced this issue Jul 31, 2018

doc/go1.11: add note to remove CLI support for godoc
Updates golang#25443

Change-Id: I5e2f84f3cee6582807b2756ffac91e8583a2baec
Reviewed-on: https://go-review.googlesource.com/126737
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
@gopherbot

This comment has been minimized.

Copy link

commented Oct 11, 2018

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

@adg

This comment has been minimized.

Copy link
Contributor

commented Oct 11, 2018

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

This comment has been minimized.

Copy link
Member Author

commented Oct 11, 2018

@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

This comment has been minimized.

Copy link
Contributor

commented Oct 11, 2018

Sounds good.

@myitcv

This comment has been minimized.

Copy link
Member

commented Oct 11, 2018

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

This comment has been minimized.

Copy link
Member

commented Oct 11, 2018

@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

This comment has been minimized.

Copy link

commented Oct 11, 2018

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

This comment has been minimized.

Copy link
Member Author

commented Oct 11, 2018

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

This comment has been minimized.

Copy link

commented Oct 11, 2018

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

This comment has been minimized.

Copy link
Member

commented Oct 11, 2018

@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

This comment has been minimized.

Copy link

commented Oct 11, 2018

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

This comment has been minimized.

Copy link

commented Oct 11, 2018

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

gopherbot pushed a commit to golang/tools that referenced this issue Oct 11, 2018

cmd/godoc: synchronously init corpus for index mode
The corpus needs to be init'd before generating the index.

Regression caused by CL 141397.

Updates golang/go#25443.

Change-Id: I04d19bf5d279031cc8ddf0f850d81eb06fc5efa8
Reviewed-on: https://go-review.googlesource.com/c/141717
Run-TryBot: Chris Broadfoot <cbro@golang.org>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

segevfiner added a commit to segevfiner/vscode-go that referenced this issue Oct 26, 2018

WIP Add completion documentation
Using `go doc` instead of `godoc` due to
golang/go#25443

`go doc` doesn't support giving the code of an unsaved file via stdin
like `gocode`, so it won't display documentation for unsaved changes.

TODO: Make sure this works for all cases, the current file, main package,
etc...

Fixes microsoft#194

segevfiner added a commit to segevfiner/vscode-go that referenced this issue Oct 26, 2018

Add item documentation to completions
Using `go doc` instead of `godoc` due to
golang/go#25443

`go doc` doesn't seem to support giving the code of an unsaved file via
stdin like `gocode`, so it won't display documentation for unsaved
changes.

Fixes microsoft#194

segevfiner added a commit to segevfiner/vscode-go that referenced this issue Oct 26, 2018

Add item documentation to completions
Using `go doc` instead of `godoc` due to
golang/go#25443

`go doc` doesn't seem to support giving the code of an unsaved file via
stdin like `gocode`, so it won't display documentation for unsaved
changes.

Fixes microsoft#194
@gopherbot

This comment has been minimized.

Copy link

commented Oct 31, 2018

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

gopherbot pushed a commit that referenced this issue Oct 31, 2018

doc: replace command line usages of godoc with go doc
Effective Go and the FAQ still had some instances which showed the command line
usage of godoc. Changed them to use go doc.

Updates #25443

Change-Id: If550963322034e6848bc466f79e968e7220e4a88
Reviewed-on: https://go-review.googlesource.com/c/145222
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

ramya-rao-a added a commit to microsoft/vscode-go that referenced this issue Nov 1, 2018

Add item documentation to completions (#2054)
* Add item documentation to completions

Using `go doc` instead of `godoc` due to
golang/go#25443

`go doc` doesn't seem to support giving the code of an unsaved file via
stdin like `gocode`, so it won't display documentation for unsaved
changes.

Fixes #194

* Code review fixes for #2054

* Refactoring and comments

* Always resolve the item

* Prompt for updating gocode if the package property is missing
@gopherbot

This comment has been minimized.

Copy link

commented Feb 18, 2019

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

@gopherbot

This comment has been minimized.

Copy link

commented Feb 18, 2019

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

gopherbot pushed a commit to golang/tools that referenced this issue Feb 19, 2019

cmd/godoc: re-add documentation for flat presentation mode
The documentation of the "flat" presentation mode was removed
inadvertently as part of post-CLI-removal documentation cleanup
in CL 143077. The FlatDir flag still exists and is supported.
This change re-adds it to cmd/godoc documentation.

Also fix a typo in the "src" presentation mode description.

Updates golang/go#25443

Change-Id: If4705d70bc5eafee92cdfd52409aca4606a0efd7
Reviewed-on: https://go-review.googlesource.com/c/162984
Reviewed-by: Agniva De Sarker <agniva.quicksilver@gmail.com>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

gopherbot pushed a commit to golang/tools that referenced this issue Feb 19, 2019

godoc: remove unused CLI-only identifiers
This is a followup to CL 141397, which removed CLI support from the
godoc command for golang/go#25443. This change removes a few more
CLI-related fields from Presentation type, which are now unused.

It also removes the unused and no longer documented (since CL 143077)
NoHTML PageInfoMode.

Updates golang/go#25443

Change-Id: Ia4147515052889570e2f050e3c2394689d3c5d6c
Reviewed-on: https://go-review.googlesource.com/c/162982
Run-TryBot: Dmitri Shuralyov <dmitshur@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
Reviewed-by: Agniva De Sarker <agniva.quicksilver@gmail.com>
@leucos

This comment has been minimized.

Copy link

commented Mar 3, 2019

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

This comment has been minimized.

Copy link
Member

commented Mar 3, 2019

@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

This comment has been minimized.

Copy link

commented Mar 3, 2019

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

@trivigy

This comment has been minimized.

Copy link

commented Mar 19, 2019

@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

This comment has been minimized.

Copy link
Member

commented Mar 19, 2019

@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

This comment has been minimized.

Copy link

commented Apr 23, 2019

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

@gopherbot

This comment has been minimized.

Copy link

commented May 17, 2019

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

gopherbot pushed a commit to golang/tools that referenced this issue May 17, 2019

godoc: declare small victory over the punched card tyranny
At least inside this one package.

It's because golang.org/x/tools/cmd/godoc no longer has CLI support
as of golang/go#25443, it is now only a web server. Luckily, browsers
that display HTML pages are not constrained to the fixed width of
punched cards. On the contrary, they seem to embrace a wide variety of
arbitrary page widths, ranging from narrow to wide. This is in part due
to the proliferation of internet access on device form factors such as
the mobile phone, tablet, laptop, and desktop.

So the punchCardWidth constant is now unused and can be removed. This
is a followup to CL 141397 that removed most of the CLI support code,
including the function comment_textFunc, which was its only user. Same
goes for containsOnlySpace.

Updates golang/go#25443

Change-Id: I61fabe6ea801c88758fb2c6aefa70b53d52e2cb5
Reviewed-on: https://go-review.googlesource.com/c/tools/+/172975
Run-TryBot: Dmitri Shuralyov <dmitshur@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.