Go: x/tools/gopls: add configuration for single-line hover

[inliquid]

Right now gopls returns only first sentence from the symbol documentation, please make it return full docs.

[stamblerre]

This is intentional. Often, documentation can be lengthy and overwhelming (token.Pos is a good example), so we try to avoid showing it all on hover. My assumption was that, if the user wanted to see more detail, they could jump to the definition of the identifier.

However, if this is not the case, and other people are also interested in this behavior, I'd be willing to make this change.

If you want to see full documentation on hover, please upvote this issue or comment with your reasoning.

[inliquid]

Actually full docs on hover was available with all editors/tools that I was using so far:

• VS Code + default command line tools
• VS Code + go-langserver
• VS Code + bingo
• Goland

From my experience it's one of the most useful and demanded features. I wouldn't mind that gopls will have a config option to disable documentation on hover. Right now cutting it to first sentence is confusing and __wrong__ because it creates wrong understanding by putting first phrase out of context and creating wrong impression for a developer that this first sentence IS the description, while it's not. It must either be full docs or no doc at all.

[marwan-at-work]

I like the small doc to not clutter everything. Before Gopls, when you hover over a signature you get a mini version of the doc (or none), but if you cmd+hover you get the full doc/definition. That was quite useful, because sometimes I just want to see the signature without having to recognize it from the docs...and sometimes I want to read the docs so I just cmd+hover

[stamblerre]

Filed https://github.com/microsoft/language-server-protocol/issues/772 to get more clarity on textDocument/hover.

[stm9443]

I personally would prefer to have full comments over the single line version, but I can understand the desire to only see the signature at times. Is it possible to add a configuration that will change the length of comments that you see on hover?

Something like: showFullComments: true (default: false)

A setting like this would allow each developer to decide the style of comments they see when hovering.

[stamblerre]

That does seem like a reasonable solution while we wait on modifications to the LSP specification. I think the options should be 1) full, 2) shortened, 3) single line (to support clients like vim-go, which currently trims to a single line).

[gopherbot]

Change https://golang.org/cl/184797 mentions this issue: internal/lsp: add configuration for hover levels

[inliquid]

I think gopls must either not show doc at all or show full docs. Cutting first sentence out of the context is simply wrong. There a lot of cases where first sentence is smth like You can use that method for anything you like. and second But do it at own risk. It's not supported. It's DEPRECATED. (exaggerating)
Adding additional click to this flow is also wrong. It's degraded user experience. Documentation on hover vs documentation on hover _+ CLICK_ is HUGE difference. In the last case you'll put VS Code with vscode-go down the bottom of rank of good Go editors.

[gopherbot]

Change https://golang.org/cl/188981 mentions this issue: internal/lsp: support single-line hover for LSP clients like Vim

[mattn]

Latest Vim have popup window. it can indicate multiple-lines. vim-lsp have already option to switch hover to popup.

[stamblerre]

@mattn: Right, I have heard that the latest versions of Vim have popups, but I think a large number of people are still using older versions. vim-go also strips hover information to turn it back into a single line, so I think it would be simpler for gopls to provide the single line, at least for now.

[inliquid]

@stamblerre how do I use this new option?

[stamblerre]

Add this to your VSCode settings:

"gopls": {
        "hoverKind": "SingleLine", // hoverKind can be NoDocumentation, SingleLine, Synopsis, FullDocumentation
}

I will add more documentation to the gopls wiki once we solidify the supported set of configurations.

[inliquid]

@stamblerre thanks, that works, I will use "FullDocumentation". Now with that option available, may I ask to move signature above the documentation, as it was done previously in sourcegraph's language server, bingo, and as in default vscode-go config with godoc or gogetdoc? Because now I have to scroll down to the bottom to just see the signature.