Re: Adding support for xref jumping to headers/interfaces

[Eshel Yaron <me@eshelyaron.com>]

Dmitry Gutov <dgutov@yandex.ru> writes:

> Hi Eshel,
>
> On 05/11/2023 10:16, Eshel Yaron wrote:
>
>>> Attached is the patch along the lines that we discussed: a new command
>>> xref-find-extra currently bound to M-' just for the sake of this
>>> experiment (eliminating the need to set up define-key to try out the
>>> "fast" workflow).
>> That's was indeed convenient for testing the patch, although in the
>> long
>> run there should probably be a different binding since `M-'` is already
>> bound to `abbrev-prefix-mark`.
>
> Honestly, it's a pretty obscure command, and the binding is
> nice. Anyway, it's not a given we'll have a new command like this, so
> there's no point in discussing bindings too early.

I agree, both that this `abbrev-prefix-mark` hardly deserves such a
precious global default binding, and that it's futile to discuss
changing that right now.

>> Personally, I would prefer a `read-multiple-choice` alternative to
>> `completing-read` here, that would allow me to select the "kind" with a
>> single key press.  Since there are rarely more than a few kinds to
>> choose from, in many cases `completing-read` introduces unnecessary
>> friction.  Ideally, the backend should be able to choose whether to do a
>> `completing-read` or a "quick" `read-multiple-choice` on a case-by-case
>> basis.
>
> People override completing-read using modes like
> icomplete-vertical-mode, but there are no popular augmentations for
> read-multiple-choice.

Sure, I also tweak and customize `completing-read`, and it's definitely
up for the task of selecting among a few candidates, but nevertheless I
think that `completing-read` is not the best tool for this job.  With
`read-multiple-choice` you make a selection with a single key, and you
don't need to press TAB to see which options are available--the prompt
tells you what each key does in case you don't know.  That's hard to
beat even with a highly optimized `completing-read` interface IME.

> Also, sometimes the types will start with the same characters, and
> sometimes not. Just using completing-read at least provides a stable
> UI for all cases: if you remember the type, you can input the first
> part of the name without thinking and press RET.

That's true, but to know which kinds are available you need to see the
list at least once, even if only to know how exactly the backend chose
to name these kinds (is it `defvar` or `variable`?).  Anyway, I don't
think this is such a crucial issue.  We can always add a
`read-multiple-choice` wrapper later, as long as the API permits it.

>> The backend can also associate stable `read-multiple-choice`
>> keys to the different kinds it support.  WDYT?
>
> Perhaps you are instead thinking of a solution when there is a stable
> keymap with known commands assigned to the same characters.

That could work too, perhaps, but what I meant is for the backend to
provide along with each kind the unique key that you press to select it.
So you always use the same key to the select the same kind with a given
backend, regardless of the set of kinds available for a specific identifier.

>>> To have something to test, I implemented this for Elisp. However, all
>>> known kinds are already printed by the regular xref-find-definitions
>>> output in that backend. So the result turned out interesting, but a
>>> little impractical: with Elisp, we already make the choice between the
>>> kinds in the Xref output buffer, when that buffer is shown at all (as
>>> Eli pointed out, actually). So... we could proceed in that direction
>>> and recommend that all kinds of definitions would be added there.
>> Yes, I've noticed that redundancy of sorts while testing this patch,
>> but I think that selecting the definition kind explicitly with this
>> new command still provides a distinct experience compared to the
>> `xref-find-definitions`.
>
> Yes, but is it better? Does it bring much to the table? For Elisp, my
> own answer is "probably not": all the kinds are available in
> xref-find-definitions, and the selection UI is adequate already (isn't
> it?)

I think that there's some benefit in being able to designate the kind of
definition you want in advance, especially if I already know which kind
I want.  In the current state of affairs, I get all definitions and then
possibly skip one or two and get to select the one I wanted.  But I
don't know in advance if the one I want will come first, or last, so I
need to take a look at the results and respond accordingly.
`xref-find-extra` (or similar) removes that bit of friction, and IMO
that's an advantage over the current UI.

>> That's indeed an added value IMO.  In that spirit, it might be better
>> for `xref-find-extra` to take the "kind" as an argument, so we can
>> define `xref-find-foo` as `(apply-partially #'xref-find-extra 'foo)`.
>> Interactively, `xref-find-extra` would still pick up the identifier
>> first and then prompt for the kind.
>
> A helper for defining new commands is definitely doable. For that
> route, though, I would like to ask whether we'll want to define any of
> them inside core Xref. And if not, then where would those definitions
> reside.
>

I would imagine that the backends should provide such commands in the
appropriate contexts, so maybe those definitions could reside alongside
the backend code?

>>> Please try out the attached (with implementation for Eglot hopefully
>>> coming soon) and let me know your thoughts (you all).
>> One issue I had was with selecting "feature" as the definition kind.
>> Basically it doesn't seem to work for some reason, so for example typing
>> `M-' isearch RET feature RET` says "No extra-defs found for: isearch".
>
> That's just a missing mapping inside xref-backend-extra-defs, I didn't
> want to spend too much time polishing the prototype.
>
>> Also, for minor mode names, we currently suggest both "function" and
>> "variable" kinds, but they both point to the same `define-minor-mode`.
>> Ideally, we'd unify the two and simply suggest "minor-mode" as the
>> definition kind.
>
> Also easy enough to do, e.g. by borrowing the solution from
> elisp--xref-filter-definitions.
>
> Still, though. It's not clear to me that improving this particular
> feature for Elisp will bring a lot to the table.

Yes, the general API is probably more interesting to then the specifics
of the Elisp backend.


Cheers,

Eshel