Re: master e630bc4fd72: ; Fix some recently added docs.

> Date: Wed, 2 Sep 2026 21:43:40 +0300
> From: Dmitry Gutov <[email protected]>
> 
> On 02/09/2026 13:23, Sean Whitton wrote:
> > -  @kbd{M-'} finds all definitions of a certain kind for the identifier
> > +  @kbd{M-g .} (or @kbd{M-g M-.}) finds all definitions of a certain kind
> 
> Thanks!
> 
> +*** New command 'M-g .'/'M-g M-.' ('xref-find-by-kind').
> 
> Unusual, but works for me.
> 
> > +This command allows you to jump to a specific kind of definition, such
> > +as a variable definition, instead of the function of the same name.
> 
> Interesting that you listed these. Personally I feel that "jump to 
> constructor" or "to face definition" are the coolest (with completion; 
> thus listing the defined structs or faces).

I agree,and I've now added those to the entry.

And I have a few comments/suggestions for this feature:

 . It is not documented anywhere which known backends support this.
   I've established by trial-and-error that the etags backend doesn't
   for example, which was disappointing, but IMO it should be at least
   documented.  Does anyone know which backends support this and which
   don't?
 . The Emacs manual says that the ELisp backend has variable, function
   alias and face among the kinds, but the actual list is much loner,
   and includes other important kinds.  Shouldn't we document all of
   them, and perhaps have index entries leading to this description in
   the user manual?
 . The UX of the prompt is sub-optimal: the list shown, at least in
   ELisp mode, is quite long, and causes the mini-window to resize.
   Would it be possible to have a shorter prompt by default, showing
   only the letters, as in "(f, v, g, m, n, a, c, e, or C-h)", where
   C-h will show the meaning of each letter?  (Btw, what is "feature"
   in this context, in Emacs Lisp code?)

Last, but not least: I miss the documentation of how to implement this
feature for a backend: what APIs need to exist and how do they plug
into the command and its subroutines.  For example, the doc string of
xref-backend-xref-kinds doesn't say how the :kind and :name properties
of the list are expected to be used by the backend and by functions
like xref-read-identifier, and looking at what elisp-mode does doesn't
help, unless you know very well what its backend does with :kind such
as defun and define-type.  Also, the doc string of
xref-backend-definitions says to use xref-make to create an xref
object, but that object is not documented well enough to understand
what it includes (the doc string refers to opaque objects), and the
ELisp backend doesn't call it in its xrefs-by-kind method, so there's
no examples to follow.  I guess the only person who'd know how to add
support for this to a new backend (like etags) is Dmitry himself,
since the documentation is impenetrable to mere mortals.

Bottom line: I think we need to make some improvements to this
feature, to make it easier to use and better documented.

Thanks.