Re: Adding support for xref jumping to headers/interfaces

[Dmitry Gutov]

Hi Eshel,

On 05/11/2023 10:16, Eshel Yaron wrote:

> Thanks for working on this feature.  I'm looking forward to using it.

Thanks for testing! Just to be clear, it's an experiment so far, to try 
to determine the best direction to go with. Whether it will be a new 
command, or several, or augmentation of some existing one(s).

> Dmitry Gutov <dgutov@yandex.ru> writes:
>
> > 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.

> > It uses the symbol at point or asks for it, then
> > polls the backend for available kinds,
>
> So far so good.
>
> > does completing-read and asks the backend for definitions of that
> > kind. And shows the list or jumps to the unique one.
>
> 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. 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.

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

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

But maybe it will be more useful for some Eglot languages, specific 
contexts and specific "kinds" to search for?

> > But let's try to answer the question: which workflows would the
> > attached approach work better for?
>
> My above suggestion to provide "quick kind selection" with something
> like `read-multiple-choice` would also be a general advantage here.
>
> > Or perhaps the main value would be in actually having separate
> > commands which could be bound to a submap with faster key sequences
> > and/or to the context menu (with context-menu-mode on).
>
> 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.

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

Does it really do certain things better than simply using 'M-.' and then 
choosing between all the available definition types inside the buffer 
(and then navigating to one with TAB)?

Or if one prefers a more dynamic interface with completions, (setq 
xref-xref-show-definitions-function #'show-definitions-completing-read) 
could fit that bill.

There is a tradeoff of not being able to just press a single char, but 
OTOH one doesn't always know which definition kind they want in advance, 
and here, the full list helps one make that choice.