Re: Adding support for xref jumping to headers/interfaces

[Spencer Baugh <sbaugh@janestreet.com>]

Dmitry Gutov <dmitry@gutov.dev> writes:
> On 07/11/2023 18:51, Spencer Baugh wrote:
>>> Perhaps it /should/ (xref-find-definitions to include both
>>> implementation and interface). And include the typeDefinition entries
>>> for langs that have those. Etc.
>>>
>>> Would the UI be worse? Let's try to find out.
>>>
>>> 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). It uses the symbol at point or asks for it, then
>>> polls the backend for available kinds, does completing-read and asks
>>> the backend for definitions of that kind. And shows the list or jumps
>>> to the unique one.
>>>
>>> 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.
>> This (and Joao's patch adding support for eglot) is very
>> interesting,
>> thank you for implementing it!
>> We also discussed a UI which shows all kinds of definitions in a
>> single
>> buffer.  Maybe the prompt for KIND should default to "all" which shows
>> all kinds of definitions?
>
> The natural question is whether 'xref-find-definitions' would be that
> UI, and if not, why not.

As in, xref-find-definitions (M-.) *by default* shows all kinds of
definitions?  That seems bad for one big reason: 90% of the time, in 90%
of languages, there's a clear meaning of "definition" and I want M-. to
take me there directly rather than prompting in any way.  But there are
other kinds of "definitions" which plausibly I could want, just
sometimes, not by default.

If you mean something a non-default version of xref-find-definitions, or
another binding for another basically-identical command, sure, I think
that would be good.  We can have both that command *and* have a command
which prompts for KIND and defaults to "all".

> Also, if "references" are included in the list of kinds (as the
> current patch for Eglot does, I think), then "show all kinds" is not
> likely to be very useful -- all will drown in "references".

True, interesting point.  I wonder if we could reasonably distinguish
"definition" kinds (a small number per identifier) from "reference"
kinds (no limit on how many per identifier).  Although I suppose there's
also no limit on how many implementations of a generic function there
can be, and that's definitely something that fits in "definitions".

Maybe the backend could decide what kinds get included in "all".  Then
it could deliberately avoid including anything "reference-like".

>> I notice the API doesn't support "fetch all kinds of definitions";
>> extra-defs requires specifying a specific kind.  Perhaps just specifying
>> a nil KIND should request all kinds, and extra-defs should tag each
>> returned object with the kind?  We could also just make a separate call
>> to extra-defs for each kind returned by extra-kinds, but that would be
>> allow less space for the backend to batch its operations.
>
> That's a question for later.
>
>>> 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). Then our
>>> solution should be more in line with either defining a number of
>>> additional named commands (for mode universal kinds) and/or making it
>>> easier to define new such commands for users/3rd-party packages/etc.
>> That's an interesting idea.  So maybe M-' (or whatever) could be a
>> new
>> prefix for a prefix-map which contains both universal and mode-specific
>> kinds of lookups.
>> So maybe something which looks kinda like (not suggesting final
>> bindings, just trying to feel out what it would be like):
>> generic eglot-find-implementation:   M-' i
>> generic eglot-find-declaration:      M-' d
>> generic eglot-find-typeDefinition:   M-' t
>
> Then we will more-or-less nail down the whole set of "available Xref
> kinds" in the core by having these commands defined.
>
> That's not very flexible, but if the set doesn't actually change too
> much, and doesn't vary between languages a lot, it could work. Would
> lead to a more straightforward design, too.

Hm, why do you say this?  This approach seems very extensible to me -
modes could add their own bindings/commands/kinds for things specific to
that mode.  But they build on top of a set of common kinds which are
provided by the core, which don't vary between language too much.

I do think that if we go with an API which has any notion of "kinds", we
should have some standard "kinds" in the core like implementation,
declaration, type-definition.  I don't see any reason not to do that.

>> xref-extra-kind, prompting for kind: M-' M-'
>
> Would we need this command, if we had separate commands for each kind
> already?

This would support kinds which:
- are language-specific,
- or are more rarely used and don't need a dedicated command,
- or are both.

>> xref-extra-kind, showing all:        M-' a
>> And if there was something mode-specific, like the Java overriding
>> method thing, it could be e.g. M-' o
>
> Most of them are mode-specific already. Some languages don't have
> separate "declarations", some don't know what "type definitions" are,
> and some, indeed, don't have method overrides.

Most languages have something that can fit into "declaration" or "type
definitions", though.

For Elisp generics, find-implementation could show the cl-defmethod, and
find-declaration could jump to the cl-defgeneric.  I would love that,
actually - I already find it rather annoying to have to navigate in the
xref buffer to the cl-defgeneric when I M-. on a generic method, if I
know up front that I want to jump to the cl-defgeneric.

Actually, this example has just convinced me that I definitely want
"kind-specific commands", even for Elisp.  That would be great.

For functions without separate declarations, find-implementation and
find-declaration could jump to the same place.  In some languages, maybe
that's just always what happens.

As for type definitions - even Elisp has things that could reasonably be
called type definitions, we just don't support jump-to-definition for
them right now.  I have no idea how we'd implement it, but we could
support jumping to cl-defstruct definitions, for example.  Maybe we
could use information from native compilation to guess the type of the
identifier at point?  But anyway, for now we'd just error if the user
ran such a command in emacs-lisp-mode or other modes that don't support
jumping to the type definition.

>> I like this sort of design a lot actually:
>
>> - it's faster to type than having to complete the kind name (IMO, having
>>    to complete the kind name makes the current patch quite clumsy)
>> - it allows a common set of keys between all modes
>> - it's extensible by individual modes without too much trouble
>> - it works naturally with context-menu-mode and other menus
>
> Indeed.
>
>>    (although I suppose we could automatically populate the context-menu
>>    with the output from xref-backend-extra-kinds)
>
> Probably.
>
>> - users could still use completing-read to type the kind
>> Plus, if we do use M-' or any other short binding for this, we
>> should
>> almost certainly make it the start of a new prefix-map rather than bind
>> M-' directly to the new command; doing otherwise would be wasteful of
>> valuable keybinding space.
>
> If we're going to have separate commands for kinds, that is indeed a
> good idea.

I almost want to say that we should have it be a prefix regardless of
whether we have separate commands for kinds.  I guess it depends:

- if we use C-M-?, that's already such a hard key to hit that maybe it's
  okay if we bind it directly to a command

- if we use M-' or something similarly convenient, it would be really
  tragic to not reclaim all that premium keybinding space.  (And
  probably if we use M-' we will need to put the old command on
  something under M-' anyway)