Re: Adding support for xref jumping to headers/interfaces

[Spencer Baugh <sbaugh@catern.com>]

Dmitry Gutov <dmitry@gutov.dev> writes:
>>>> 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".
>>>
>>> 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.

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

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

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

>>> It is less flexible because any time a backend wants to use a new
>>> "kind", it will need to expend some effort and add it to the core
>>> somehow. Define a new command or two and assign them to the said
>>> prefix map. This could also lead to conflicts if backend authors don't
>>> do this carefully enough.
>> No, I suggest that xref-backend-extra-kinds should be able to return
>> whatever arbitrary symbols it wants.  Just, if its "kinds" match the
>> kinds used in the core, then it will benefit from the commands and
>> bindings defined by the core.
>> Perfectly extensible, but still benefiting from standardization.
>
> Would the user be able to input/use the kinds that are in the list
> returned by the backend but are not in the set of "kinds used in the
> core"? If yes, how? Using a backend-provided command?

With xref-find-extras, which prompts for a kind.

>>>> 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.
>>>
>>> We could have a "registry" of kinds, associating each of them with a
>>> key. Then the result could be more dynamic, e.g. M-' could be bound to
>>> a command that reads the key and performs the dispatch to the
>>> corresponding search (similar to project-switch-project).
>>>
>>> And the users (though probably not packages) would later be able to
>>> customize that mapping, adding new kinds or modifying the keys.
>>>
>>> With this approach we don't end up with many xref-find-xyz commands,
>>> most of which just clutter the namespace, staying unused for a large
>>> proportion of the users. OTOH, one wouldn't be able to examine the
>>> prefix map and its contents and definitions with (M-' C-h) -- that's a
>>> minor reduction in usability.
>> The only difference between this and a regular keymap which maps
>> keys to
>> commands is:
>> 
>>> we don't end up with many xref-find-xyz commands
>> But we can also avoid that by just... not defining many such
>> commands
>> and kinds.  A mode will always have the ability to define its own
>> mode-specific kinds in the mode's own namespace, which don't clutter
>> xref-*.
>
> Indeed.
>
> 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.

>>>> 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.
>>>
>>> Aren't find-implementation included in find-definition anyway? Or
>>> *are* the same as find-definition, for example, in LSP's approach?
>>> Aside from the fact that the latter also works for variables and other
>>> symbols.
>> No, find-implementation shows all the implementations of a generic
>> function/interface method.  (e.g. cl-defmethod)
>> find-definition (as I understand it) jumps to the interface
>> definition
>> itself (e.g. cl-defgeneric).  Which in my experience in Elisp, is
>> usually what I want; I want to see the documentation and default
>> implementation and surrounding code, before I look at a specific
>> implementation.
>
> I usually want to jump to where the function is
> implemented. Preferably, for the given type (though we don't support
> that). Perhaps I would use the proposed xref-find-implementations for
> this purpose, but it's bound to have a more complex key sequence than
> 'M-.'.
>
>> I think that's a pretty reasonable way for it to work.  Actually, maybe
>> we could add a customization point for the Elisp backend so that a user
>> can choose to make find-definition work that way, if we do add a
>> find-implementation command.
>
> We could.
>
>> 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.