bug#64101: 29.0.91; Eglot inlay hints rendered out of order

[Stefan Monnier]

>> Should the overlays created for the
>> inlay hints be forced to be sorted in some particular order?
> Maybe, and there is definitely an order they should be sorted.

If they start and end at the exact same place, then the ordering by
default is arbitrary (IIRC it's sorted by memory address, simply
because we needed some cheap way to make the ordering total).

If you need a particular ordering between such overlays, then you
definitely need to use the `priority` property.

> --- a/lisp/progmodes/eglot.el
> +++ b/lisp/progmodes/eglot.el
> @@ -3755,8 +3755,9 @@ eglot--update-hints-1
>                       (if peg-after-p
>                           (make-overlay (point) (1+ (point)) nil t)
>                         (make-overlay (1- (point)) (point) nil nil nil)))
> -                   (do-it (label lpad rpad firstp)
> -                     (let* ((tweak-cursor-p (and firstp peg-after-p))
> +                   (do-it (label lpad rpad i)
> +                     (let* ((firstp (zerop i))
> +                            (tweak-cursor-p (and firstp peg-after-p))
>                              (ov (make-ov))
>                              (text (concat lpad label rpad)))
>                         (when tweak-cursor-p (put-text-property 0 1 'cursor 1 
> text))
> @@ -3767,17 +3768,18 @@ eglot--update-hints-1
>                                               (1 'eglot-type-hint-face)
>                                               (2 'eglot-parameter-hint-face)
>                                               (_ 'eglot-inlay-hint-face))))
> +                       (overlay-put ov 'priority i)
>                         (overlay-put ov 'eglot--inlay-hint t)
>                         (overlay-put ov 'evaporate t)
>                         (overlay-put ov 'eglot--overlay t))))

The `priority` property is a source of problem in itself so I'd
recommend to use its weaker version where the value is a cons cell
`(nil . SECONDARY)`.  This way the SECONDARY priority will only be used
as a last recourse (before using pointer addresses).

The doc discourages this use because when I introduced it (for use by
the Lisp reimplementation of the region highlighting, some time around
Emacs-24) I wasn't too sure how it would play out.  But I suspect we
should change the doc to let people use it without a bad conscience (or
maybe even encourage its use).


        Stefan