Re: Adding support for xref jumping to headers/interfaces

[Dmitry Gutov <dmitry@gutov.dev>]

On 11/11/2023 15:00, Spencer Baugh wrote:

>>>> We could indeed, if we decide what to call it. "extras" seems out
>>>> (since it would include both definitions and additional reference
>>>> kinds). Just "xref-find-by-kind"? Then it's less obvious to have the
>>>> default behavior showing all.
>>> Actually, maybe this should be a backend-specific thing.  The
>>> backend
>>> could specify a default along with its list of kinds.  And if we request
>>> that default kind (which might be 'all), then the backend will decide
>>> what kinds to send us.
>>
>> If the backend specifies the default behavior of xref-find-by-kind,
>> then it's what, another generic method to override?
> 
> The default could just be the first in the list of kinds returned by the
> backend.

So... one backend would show implementations, another "all kinds", and 
the third one "definitions"? That seems odd.

Moreover, if I don't have any idea what the average backend would do, 
it's harder to write the docstring, or describe the command in the 
manual (check out the current manual entries related to Xref; that 
wasn't me who wrote them).

I was also thinking to suggest the command name 
xref-find-all-definitions, but that one clearly implies what its 
behavior will be when called without prefix.

>>> Actually, it occurs to me that if we had an xref-find-implementations
>>> command from the start, with a convenient binding, maybe
>>> xref-find-definitions would just only show the cl-defgeneric, and jump
>>> to it right away.  And only if you hit xref-find-implementations would
>>> you jump to the cl-defmethods.  We can't make that change now, but I
>>> don't think it would be worse!  And if a backend wants a design like
>>> that, I think the backend should be able to have it.
>>
>> Not sure I would like the result that you are describing, but indeed,
>> if a backend wants to do it like this, nothing will be stopping it.
>>
>> Are LSP servers behaving like this? E.g. jdt-ls jumping to the method
>> definition in an interface, even when the owner type is a statically
>> known class?
> 
> I don't know about jdt-ls or indeed about LSP servers, but the xref
> backend for Merlin (used for OCaml) by default has xref-find-definitions
> jump to the signature of a function, not its implementation.

Unfortunately, I don't have an intuition for how this works for OCaml in 
other editors, or worked in the past, to compare.

> There's a user customization to toggle whether it jumps to the signature
> or the implementation.  And if the customization is in "implementation"
> mode, there's no way (through xref) to jump to the signature, and vice
> versa.  Adding a way for xref to support jumping to the signature in
> cases like that is in fact why I made this thread in the first place. :)

Sounds like a good goal.

>>>>> Maybe the backend could decide what kinds get included in "all".  Then
>>>>> it could deliberately avoid including anything "reference-like".
>>>>
>>>> Could we want several such commands? E.g. one for "all definition-like
>>>> hits" and another for "all reference-like hits"? With separate sets of
>>>> kinds for definitions and references?
>>> Possibly, but my suggestion is that "all definition-like hits" and
>>> "all
>>> reference-like hits" should just be kinds exposed by the backend.
>>
>> Two different generics returning lists of kinds, or just one? If two,
>> then could one give an example of a "reference-like" kind except for
>> "references"? I've taken a couple of guesses, but I'm exactly sure of
>> them.
> 
> One generic.  Just "all-references" is a kind, and "all-definitions" is
> another kind.

Then how will xref-find-by-kind (or xref-find-extras) decide whether to 
use xref-show-definitions-function or xref-show-xrefs-function to 
display the result?

>> But if we don't define a dynamic dispatcher at all, it seems we won't
>> need the backend to tell us about the supported kinds either. It would
>> just support some and perhaps return error for unknown kinds.
> 
> True, in theory we could do that.  We could even provide some way to ask
> the backend, "do you support kind X?" which could be useful to avoid
> making bindings for something not supported by the backend.
> 
> So we could start without xref-backend-extra-kinds, and probably could
> get decently far.
> 
> However, I think the dynamic dispatcher is useful for one very important
> thing: when the backend adds support for a new kind which the major-mode
> and/or core has not yet added support for.  Users will definitely want
> to be able to use features of the backend that their major-mode/the core
> doesn't know about.

I thought we might have decided that the backend would create its own 
specific command for that (e.g. called 
eglot-find-higher-order-template-cxx-macroexpansion-definitions).

We could also create a command for dynamic dispatch. Supplying both is 
also fine, I suppose, but a little redundant.

>>> There's also find-declaration - for Elisp, I think that one *is* the
>>> mostly same as find-definition, since Elisp doesn't have separate
>>> declarations.  (declare-function is kind of a different thing.  Maybe
>>> find-declaration should jump to the declare-function instance in the
>>> current file, if it can, but for now it's fine.)
>>
>> Yep. Though for cases where there is no corresponding meaningful
>> implementation, I would rather abort with an error. Doing otherwise
>> seems misleading (like we have special handing of this case, but we
>> don't).
> 
> BTW, talking with Joao has convinced me that actually these should be
> major-mode specific.  So we can have emacs-lisp-find-generic or
> whatever, and that can have all kinds of special behavior and a useful
> docstring that takes about Elisp things, but ultimately it calls into
> the xref backend with a specific kind.

Useful docstrings are nice, and I suppose some modes would define their 
own special commands, but it seems difficult to assign them to the same 
prefix-map, for one thing. If we use a prefix map on M-', 
emacs-lisp-mode couldn't add a binding to it without modifying it globally.

OTOH, modes can use the [remap] binding, but only when the original map 
contains a binding and a command that the current major or minor mode is 
interested in installing a local variant of.