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/gopls: support for an IDE documentation viewer #55861

Open
firelizzard18 opened this issue Sep 25, 2022 · 7 comments
Open

x/tools/gopls: support for an IDE documentation viewer #55861

firelizzard18 opened this issue Sep 25, 2022 · 7 comments
Labels
FeatureRequest gopls Issues related to the Go language server, gopls. Tools This label describes issues relating to any tools in the x/tools repository.

Comments

@firelizzard18
Copy link
Contributor

firelizzard18 commented Sep 25, 2022

I propose adding a documentation request/response to gopls. As a user, I want to easily view documentation for the code I'm working on, and ideally for private modules I am using. As a developer, I am interested in contributing a documentation viewer to the VSCode extension.

I've considered a number of possibilities for adding a documentation viewer to the extension. Fundamentally, any such solution must involve either parsing Go or go doc comments in JavaScript/TypeScript, or calling a separate binary. Not wanting to build a parser, I explored using godoc or gddo. Using a server model is annoying because the extension would need code to manage the lifetime of that server. On the other hand, calling a binary to parse a given file is less code but more overhead and either of the aforementioned tools are particularly suited to that - I spent a couple days exploring that.

I think an elegant solution would be to add a method to gopls that requests documentation for a given symbol or package:

  • gopls already has tooling for reading and parsing source
  • go/doc can be used to parse doc comments
  • When gopls is built with Go 1.19+, go/doc/comment can be used to provide richer output

I am interested in implementing this. Hopefully parsing doc comments for workspace files will be relatively simple. For other packages, I can leverage the fact that gopls already knows how to determine which version of a package is in use and knows how to locate that file in the module cache.

@gopherbot gopherbot added Tools This label describes issues relating to any tools in the x/tools repository. gopls Issues related to the Go language server, gopls. labels Sep 25, 2022
@gopherbot gopherbot added this to the Unreleased milestone Sep 25, 2022
@firelizzard18
Copy link
Contributor Author

firelizzard18 commented Sep 25, 2022

@gopherbot, please remove label Documentation

This relates to documentation, but it is a task to write code, not to write documentation.

@firelizzard18
Copy link
Contributor Author

firelizzard18 commented Sep 25, 2022

@gopherbot, please add label FeatureRequest

@hyangah
Copy link
Contributor

hyangah commented Sep 30, 2022

Thanks for filing the feature request.

We discussed this feature during our triage meeting.

I personally dreamed of this feature. But for long-term maintainability, we will need careful design, discussion, and code review.
Unfortunately, the gopls team does not have bandwidth for the needed support right now.

It looks like you were thinking to implement this as a custom gopls command. Gopls custom command is not too different from running a separate command except that the command can have access to the parsed go files already. However, that information should be also available with golang.org/x/tools/go/packages and go list too.

How about making this feature as a separate command & extension first?
Prototype & demo may help people see the value of this feature more clearly.

  • Another aspect to consider: if it is implemented using gopls custom commands, it's likely that only certain editors (e.g vscode) that can implement UI frontend will benefit from this feature. If it's implemented as a web server (maybe running on gopls?), other editor users may utilize the feature through web browsers.

@hyangah hyangah modified the milestones: Unreleased, gopls/unplanned Sep 30, 2022
@firelizzard18
Copy link
Contributor Author

firelizzard18 commented Sep 30, 2022

Gopls custom command is not too different from running a separate command except that the command can have access to the parsed go files already.

In my view the main differences are that using gopls requires less additional code and gets the advantage of a long-running process that can cache work without the complexity of managing an additional process.

How about making this feature as a separate command & extension first?
Prototype & demo may help people see the value of this feature more clearly.

👍

Another aspect to consider: if it is implemented using gopls custom commands, it's likely that only certain editors (e.g vscode) that can implement UI frontend will benefit from this feature. If it's implemented as a web server (maybe running on gopls?), other editor users may utilize the feature through web browsers.

Taking HTML output from a tool and embedding it in a webview puts significant restrictions on integration with the IDE. I experimented with taking HTML output from gddo (or was it godoc?) and putting it in a webview. IMO that experience is not good. I feel the same about the pprof webviewer, but I am not going to write a custom profile viewer so it's good enough.

For documentation, I want the command to provide structured data about the package and I want it to be the extension's responsibility to convert that to a UI.

@Southclaws
Copy link

Southclaws commented Nov 1, 2022

I've recently run into this as I wanted to provide a ton of documentation and examples with properly formatted text on pkg.go.dev but the existing godoc tool doesn't support all this formatting so it comes down to either trial and error pushing and waiting for go.dev to pick up the changes or try to run pkgsite locally (which isn't well documented and requires a ton of external dependencies like a database and message queue from what I can tell)

So I'd like to help on this, I'd love to see something like this land in the official vscode extension or some feature in gopls. Perhaps we could collaborate on a proof of concept?

@aarzilli
Copy link
Contributor

aarzilli commented Nov 1, 2022

the existing godoc tool doesn't support all this formatting

Support for the new formatting (links, lists and headings) was added to godoc in 79f3242e4b2ee6f1bd987fdd0538e16451f7523e

@Southclaws
Copy link

Southclaws commented Nov 1, 2022

Oh I didn't know about that! I'm on quite an old version, thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
FeatureRequest gopls Issues related to the Go language server, gopls. Tools This label describes issues relating to any tools in the x/tools repository.
Projects
None yet
Development

No branches or pull requests

5 participants