Language-server-protocol: offer more configuration for textDocument/hover

[stamblerre]

Because the hover result is either a string or a markdown string, it's hard to offer users more configuration over their hover results.

A good example of this is this issue raised against gopls: https://github.com/golang/go/issues/32561. Some users want to see full documentation on hover, while others prefer to see one sentence of the documentation, while others may prefer to see none at all.

Personally, my preferred solution would be to offer users a "see more" option, something like holding down Command and hovering over an identifier. Right now, that just previews the declaration of the identifier, but perhaps it could be something like a detailed hover?

Is there any chance that the textDocument/hover could have a detailed configuration, or maybe there could be an additional textDocument/detailedHover? I would suspect that most languages return some combination of documentation and signatures/type declarations, so maybe hover could even be more structured than just a string?

Otherwise, I will likely add additional configurations to gopls to control the level of hover. I figured it was worth raising this issue because I suspect other languages would encounter these questions as well.

[dbaeumer]

To stay in line with other request we should improve this in the following way:

• have a HoverItem result type
• have a content property that is MarkupContent
• have an optional details property that is MarkupContent
• have a hover/resolve request to resolvethe details value is needed.

I am open to such a improvement. However it needs to be speced and we need to have a reference implementation for it.

[alanz]

This feature would also help for emacs-lsp, where the hover request is used both to provide the documentation for the current focal point, but also to get summary information for variables in the local context. So have either a two-level request, or a two-level reply would help.

See https://github.com/emacs-lsp/lsp-ui/issues/292

[stamblerre]

To add a bit more to this issue - https://github.com/golang/go/issues/33352 was just raised in gopls. To me, it seems like the best solution for this issue would be to have a more structured return type from textDocument/hover. I would expect that most languages return some combination of documentation and a signature--would it be possible to separate the two in the hover result?

[stamblerre]

@dbaeumer: Just to clarify, would I be able to contribute the solution for this issue, or would it have to be someone who works on the LSP?

[dbaeumer]

@stamblerre sorry for the late reply. Yes, I would accept a PR for this. However as state we need a reference implementation for it in one of the editors / tools. It can't only be a spec update.