x/tools/gopls: document code actions that gopls supports

[findleyr]

From discussion on gophers slack: it would be nice if gopls documented supported code actions, similar to how it documents other parameterized features (such as inlay hints: https://github.com/golang/tools/blob/master/gopls/doc/inlayHints.md).

Supported code actions are provided part of the initialize handshake, but we could document more precisely what we support.

[advinsuryavanshi]

can i work on this...?

[findleyr]

@advinsuryavanshi yes, contributions are very welcome!

However, be warned that we may want more than just pure documentation here. As much as possible, we try to generate our documentation from the gopls source. This prevents duplication, and helps ensure that documentation doesn't go stale. It also makes it easier to compile our documentation into JSON that can be read by editors. You can see examples of this in x/tools/gopls/doc/generate.go.

I haven't thought too much about code actions, but we should try to do something similar, basing our documentation off of x/tools/internal/lsp/source.DefaultOptions().SupportedCodeActions. One way to enforce that we have documentation would be to change the type of SupportedCodeActions. For example:

    SupportedCodeActions map[FileKind]map[protocol.CodeActionKind]string // file kind -> action kind -> description

In the future we could also go further and try to refactor such that code actions are parameterized, similarly to inlay hints (see x/tools/internal/lsp/source.AllInlayHints), but I don't think it is wise to undertake that refactoring now.

CC @suzmue @jamalc who may have opinions, having just done this for inlay hints.

[jeanbza]

Just piping in to ask a naive question: is this intended to replace (the presumedly manually maintained) https://github.com/golang/tools/blob/master/gopls/doc/commands.md ?

If so, maybe linking to https://github.com/golang/tools/blob/master/internal/lsp/command/interface.go is a good easy first step: seems pretty self-explanatory, and only seems to lack the name of each command (RunTests vs gopls.run_tests). But maybe that can just be added to the comment.

Hacky solutions, but ones that might yield results quicker than trying to auto-generate documentation.

[findleyr]

@jadekler sorry for missing your question. Code actions may return either workspace edits or commands, so there is a lot of overlap with the command documentation but they are distinct. I think the point of documenting code actions is that users can bind keys to specific code action workflows.

I recently refactored the code action code somewhat for performance reasons (https://go.dev/cl/511995), after which it is slightly easier to see which code action kinds are supported.

I don't think we need to block this issue on perfectly parameterizing the code action logic. If anyone wants to help out on this, I think it would be suitable to start out with manual documentation:

• create a codeActions.md at https://github.com/golang/tools/tree/master/gopls/doc
• read through the source code at https://github.com/golang/tools/blob/master/gopls/internal/lsp/code_action.go, searching for protocol.<name> to see where different code action kinds are handled.
• document each supported code action kind, and approximately how it is implemented (for example, we can say that organizeImports integrates with goimports).

In the future, it would be nice to have a code action dispatcher similarly to what we have for the executeCommand request. At that point perhaps we could automate documentation.

@adonovan is currently working on refactoring (doing some very exciting work on inlining!), so now is a good time to start revisiting this code and documentation.

[gopherbot]

Change https://go.dev/cl/583316 mentions this issue: gopls/doc: document all of gopls' features