:company-docsig support

[jdtsmith]

A very useful company property many backends provide is :company-docsig, which is a function which gives a short documentation signature (the same as eldoc usually). UI's usually show these in the echo area as you select through completion candidates.

This would be a great lsp-mode addition. Thanks for considering.

[yyoncho]

The question is which property from the lsp spec should we show there...

[ericdallo]

yeah, the documentation could be large to show on the echo area, right? maybe only the first line of the docs as we do with eldoc would be good?

[jdtsmith]

It's typical to use the same thing eldoc gives in the echo area. I'd personally find it useful to have both calling syntax and the 1st line of doc prose.

[yyoncho]

@jdtsmith we cannot obtain it, because the text has to be inserted in the buffer in order to get its docs. That is how the protocol works.

[jdtsmith]

Interesting. There is the documentation tag in the completionItem, but it is apparently resolved "lazily", upon request by the client:

The Completion request is sent from the client to the server to compute completion items at a given cursor position. Completion items are presented in the IntelliSense user interface. If computing full completion items is expensive, servers can additionally provide a handler for the completion item resolve request (‘completionItem/resolve’). This request is sent when a completion item is selected in the user interface. A typical use case is for example: the textDocument/completion request doesn’t fill in the documentation property for returned completion items since it is expensive to compute. When the item is selected in the user interface then a ‘completionItem/resolve’ request is sent with the selected completion item as a parameter. The returned completion item should have the documentation property filled in. By default the request can only delay the computation of the detail and documentation properties.

Do you know if servers usually return useful documentation upon completionItem/resolve? If so, I guess the trick is having the completion UI's communicate back to LSP mode that a given candidate has been selected, match that to the completionItem, and send it back as a completionItem/resolve.

[yyoncho]

@ericdallo

yeah, the documentation could be large to show on the echo area, right? maybe only the first line of the docs as we do with eldoc would be good?

Tested with a few servers, it won't work well.

[yyoncho]

@jdtsmith

Interesting. There is the documentation tag in the completionItem, but it is apparently resolved "lazily", upon request by the client:

There is already :company-doc-buffer for the docs.

[jdtsmith]

Aha, thanks. That uses resolve? If so, I wonder if it would be possible to have docsig do the same thing and show 1st line only, caching documentation locally for any later doc-buffer calls? This is for an alternative completion UI btw.

[yyoncho]

Caching is not an issue here. Using the first line/sentence doesn't seem to make sense because this is not docsig but just the first line of the docs(it won't be the same thing that we display for eldoc).

[jdtsmith]

I'd definitely find it very valuable to see that 1st line when sorting through a bunch of similar-sounding function names! Caching would only be so that if the user later (during the same completion session) invokes the full doc-buffer, lsp-mode wouldn't have to contact the server again. Interestingly for numpy with pyright, eldoc does just show the full docstring.

[yyoncho]

@jdtsmith have you considered using https://github.com/company-mode/company-quickhelp or similar? It will show the docs in popup near the completion selection dialog?

[minad]

@yyoncho It shouldn't be a problem to create a company-quickhelp analogue for Corfu. Nevertheless :company-docsig support in lsp-mode would be neat for people who prefer less obtrusive UIs. A documentation message in the echo area is less distracting than a large documentation popup.

[yyoncho]

@minad I am not against supporting it but my concern is that if we implement it in a hacky way over lsp protocol(because there is no 100% match in the spec) it will cause people to complain. In this case, I think that on lsp-mode side the best implementation will be to take N chars from doc and return it in docsig otherwise it may cause resize of the modeline. The same thing can be implemented on the front-end side.

[jdtsmith]

I just worked up a proof of principle shimming in a :company-docsig property, which runs the :company-doc-buffer function, pulling the first non-blank line out. Seems to work OK.

On a related topic, I noticed eldoc places the entire (truncated to about a half page) doc string into the echo area. Is this expected?

BTW, the highlighting for function arguments in lsp-mode's eldoc is exceptional! I'd only ever seen that for emacs-lisp. A big advantage. Thanks for all your work.

[jdtsmith]

To circle back on this, I don't think my hackery to shim in a :company-docsig is a good solution, but does demonstrate the utility. It would be better if lsp-mode itself provided the "first-n-chars of doc as docsig" option. It's too bad LSP only gives you full access to parameters/etc. after the text is in buffer.