Re: Adding support for xref jumping to headers/interfaces

[Dmitry Gutov <dmitry@gutov.dev>]

On 27/11/2023 17:03, João Távora wrote:
> On Mon, Nov 27, 2023 at 2:35 PM Dmitry Gutov <dmitry@gutov.dev> wrote:
> 
>> But one of the latest emails mentioned a separate Xref backend for c/c++
>> -- should I assume that every such backend would define its own set of
>> *-find-* commands suitable for its languages?
> 
> Of course, a cross-referencing backend should know what kind of
> cross-references it can find.  Eglot knows how to find 3 or 4 different
> kinds, language server permitting of course.

That didn't answer the above question. To signal "what kind of 
cross-references it can find", it would define 
xref-backend-definition-kinds with corresponding return value.

> Eglot will never know how
> to find "documentation", and I believe the Elisp backend should
> never purport to know how to find "declaration", since that's a very
> fuzzy concept in Lisp with no accepted meaning.  As is
> "typeDefinition", doesn't make much sense in dinamically typed
> languages (but "declaration" is worse).

Dynamic languages have type checkers and inferencers implemented all the 
time. E.g. There's nothing stopping someone from analyzing a stack of 
definitions in Elisp, seeing that a variable is either defined with a 
cl-struct's constructor, or accessed with a cl-struct's accessor, and 
assuming that struct's definition as its type definition. Same for EIEIO 
and its counterparts in Common Lisp. In Ruby and Python, we have 
optional type annotations as well, provided by libraries (Ruby) and the 
core language (Python).

>> Would such backends each come with an automatically-enabled keymap? Or
>> would the user have to set up key bindings for every such command, for
>> every special backend like that?
> 
> The major modes could do that, for example.  They could do it by
> linking the backend-created "one key/command" keymap into a special
> prefix created by xref.el, doing so by calling a load-time xref.el helper.

Okay, so we would create and occupy a new common prefix. But without any 
commands in it? How do you suggest we advocate for that around here?

> So maybe some backends would have d for  "documentation" and others would
> have d for definitions, so what? Maybe that's precisely what a user working
> on a documentation heavy system expects "d" to do. And if these two backends
> happen to be enabled simultaneously,  even this conflict could be
> resolved, by adjusting the keymap during the linking process.

That's easily solvable in other ways.

First of all, xref-find-definitions is bound already, and I'm sure 
text-related backends have its own "things" found by it, ones that you 
wouldn't readily call "definitions" (there was a bug report related to 
LaTeX not too long ago about a situation like that, IIRC).

But if you wanted to take "d" from "declarations" instead, then, with 
core Xref commands it's easy to override. Something like:

   (define-key well-learned-mode-map [remap xref-find-declarations] 
#'well-learned-find-special-documentation)

With the benefit that a known key binding is used.

> But however this works, I think the bindings issue is completely
> secondary.  Secondary not in the sense that it's less important,
> but in the sense that we don't have to commit to something right
> now, so I don't understand the tortuous route this feature is taking into
> what-if territory.

If we don't have built-in bindings (or a prefix map), we miss an 
opportunity to make life for Xref backends' implementors easier. But 
indeed, it could be deferred.

But another issue is that if we drop the commands, we lose the fastest 
way to access the definitions for each kind OOtB. Then we're back to 
discussing how the new command which allows accessing different kinds 
(the unlimited set) could be made faster/more predictable than just 
using completing-read. E.g. with a customizable registry of key->kind 
mappings.

And I didn't just invent the need for faster interaction by myself - 
just look at the first responses to the prototype. Okay, perhaps some 
power users in this thread don't mind adding personal tweaks to their 
config to speed things up. But that means the OOtB experience will be 
lacking.

> So whatever solution we find to the bindings issue (if it is indeed
> an issue)
> 
> It's much more pressing to decide if/why you want a command named
> xref-find-all-definitions to return things that aren't "definitions"
> by any measure or what is pressuring us to enshrine
> "declaration/implementation/typeDefinition" in one of our
> most generic libraries.

It's a framework, not so much a library. Although it has the latter's 
capabilities too. As a framework, we should consider what the end user 
experience would look like.