bug#62687: 30.0.50; Eglot (eglot--sig-info): SignatureInformation's Documentation is never shown when it's of type MarkupContent

[Mekeor Melire <mekeor@posteo.de>]

[-- Attachment #1: Type: text/plain, Size: 2744 bytes --]

2023-04-06 19:49 mekeor@posteo.de:

> 2023-04-06 19:21 mekeor@posteo.de:

> >            (string-match "[[:space:]]*\\([^.\r\n]+[.]?\\)"
> >                          documentation))
> >   (setq documentation (match-string 1 documentation))
>
> Here, we trim the beginning of the documentation-string and 
> extract the first sentence; or rather: We extract the text up to 
> the first dot.
>
> (I guess here is another bug because this regex will cut 
> "a().chain().like().this()" (which might occur inside a 
> documentation-string) off right after the first dot.)
>
> I guess, the motivation for these lines is to reduce the size of 
> the echoed documentation message; i.e. prevent flooding of the 
> echo-area. Large echo-areas take up much of the screen and are 
> annoying.
>
> Personally, I don't think that we should extract only one 
> sentence or so. Instead, I think, `max-mini-window-height' (and 
> `eldoc-echo-area-use-multiline-p') suffices to configure the 
> maximum size of the echo-area.
>
> But, if we decide to stick to the idea of only echoing the first 
> sentence, then I wonder: How do we implement this feature for 
> documentation-markups? How to extract the first sentence of a 
> markup? `string-match' would not work, right?

Another idea would be to echo the documentation up to the first 
newline. That would work especially nice if we stick to use ": " 
as separator between label and documentation. See below.

> >   (unless (string-prefix-p (string-trim documentation) label)
>
> This line makes sure that we do not echo the "first sentence" of 
> the documentation-string if it's a prefix of the label. How 
> often does this happen? Has this been reported as a bug before? 
> It seems rather unlikely to me.
>
> Also, if we decide to stick to this feature, then I wonder: How 
> to recreate the logic of `string-prefix-p' for documentations of 
> type markup?
>
> >     (goto-char (point-max))
> >     (insert ": " (eglot--format-markup documentation))))
>
> Here, we finally format the "first sentence" of the 
> documentation-string and insert it into the temporal buffer 
> which will be echoed later.
>
> Also, does it make sense to pass a documentation of type string 
> into `eglot--format-markup' which will format it as 
> GitHub-Flavored-Markdown (GFM) although the documentation is not 
> of type markup?

Additionally, I don't think that ": " is a good separator between 
the previously inserted label and the documentation. I think we 
should use a newline.

Alternatively, we could make that separator customizable.

But if we decide to stick to ": " as separator, here's a minimal 
patch that makes Eglot echo the SignatureInformation's 
Documentation -- even if it's of type MarkupContent:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 62687.patch --]
[-- Type: text/x-patch, Size: 1385 bytes --]

diff --git a/lisp/progmodes/eglot.el b/lisp/progmodes/eglot.el
index 10b6c0cc2ca..a4f859745e7 100644
--- a/lisp/progmodes/eglot.el
+++ b/lisp/progmodes/eglot.el
@@ -3128,14 +3128,12 @@ for which LSP on-type-formatting should be requested."
           (setq params-start (match-beginning 2) params-end (match-end 2))
           (add-face-text-property (match-beginning 1) (match-end 1)
                                   'font-lock-function-name-face))
-        ;; Decide whether to add one-line-summary to signature line
-        (when (and (stringp documentation)
-                   (string-match "[[:space:]]*\\([^.\r\n]+[.]?\\)"
-                                 documentation))
-          (setq documentation (match-string 1 documentation))
-          (unless (string-prefix-p (string-trim documentation) label)
-            (goto-char (point-max))
-            (insert ": " (eglot--format-markup documentation))))
+        ;; Insert documentation
+        (goto-char (point-max))
+        (unless (null documentation)
+          (insert ": " (if (stringp documentation)
+                         documentation
+                         (eglot--format-markup documentation))))
         ;; Decide what to do with the active parameter...
         (when (and active-param (< -1 active-param (length parameters)))
           (eglot--dbind ((ParameterInformation) label documentation)