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>]

Let's take a closer look at the relevant code snippet; understand 
its bug; understand its features; and try to come up with a 
solution.

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

> (when (and (stringp documentation)

This line is the reason why the documentation is only echoed if 
it's of type string, and why it will never be shown in case it's 
markup content.

>            (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?

>   (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?