Re: [PATCH] (icomplete-vertical-mode): Add support for affixations and, annotations

[Daniel Mendler <mail@daniel-mendler.de>]

On 5/28/21 10:34 AM, João Távora wrote:
> Daniel Mendler <mail@daniel-mendler.de> writes:
>>
>> A better design for the problem of annotations, which we are actually
>> discussing here is a `decoration-function` as proposed João. This
>> decoration function has the sole purpose of providing additional
>> decorations. Unrelated features should be provided by unrelated
>> additional functions. The decoration function should return a
>> plist/alist of all decoration fields. Then one may want to add a
>> `fields` argument to restrict the set fields in case the UI only needs
>> the prefix and suffix. A tabular list UI can then present all the fields
>> as returned by the decoration function.
> 
> There has to be a misunderstanding here, because naming aside, this is
> exactly how I read Juri's proposal of a resolution-function, which I'm
> fine to call decoration-function or fancification-function etc.

No, there is no misunderstanding here. The example sent by Juri contains
'doc-buffer, 'docsig and 'location, which are all Company extensions and
which cannot be considered annotations or decorations.

The name `resolution-function` does not suggest that the function is
supposed to return annotations or decorations. It can return anything -
this is the over-generalization I am talking about.

> Again, I can't understand this.  In the frontend:
> 
>     (let ((res-fun
>              (or (completion-metadata-get md resolution-function)
>                  (plist-get completion-extra-properties :resolution-function))))
>       (let* ((fields-i-know-how-to-handle '(suffix location))
>              (str candidate-i-am-about-to-decorate)
>              (field-values
>                (mapcar (lambda (f) (funcall res-fun str)) fields-i-know-how-to-handle)))
>          ...))

This is not an extensible design. I would like that the frontend has the
ability to show arbitrary fields, not only fields it already knows of.
Then the completion UI can for example display the supplied annotations
in a tablist as columns. The backend can decide and extend the list of
annotation fields itself. This makes sense since the UI cannot foresee
all kinds of semantic annotation fields up front.

So to summarize - I consider the current design lacking:

1. It is not extensible. The backend cannot define fields.
2. It is over-generalized, since the function returns not only
annotations but also arbitrary data.

There is no point in the over-generalized design, since metadata is
already extensible with functions or data. Going via the
`resolution-function` only introduces a needless complication and
indirection.

I am proposing the addition of a `decoration-function` which has the
single concern of providing annotations/decorations. The simplest design
from is something like a generalized `affixation-function`:

(funcall decoration-function "candidate") --> (:candidate
"formatted-candidate" :prefix "prefix" :suffix "default suffix?"
:my-annotation1 "suffix" :my-annotation2 "suffix2" ...)

Then the UI can present prefix, formatted candidate and suffix and the
additional annotations in a tablist. Maybe it is not necessary to
specify a `:suffix` field - the additional annotations could be treated
as suffixes in the default UI.

I hope we can back to a simpler design here, which solves the problems
we are having at the moment - adding annotations or even only prefixes
and suffixes.

Daniel