Re: master b02c9bc: Improve documentation of new Xref options

[Dmitry Gutov]

On 08.09.2021 09:18, Eli Zaretskii wrote:

> > But the feature doesn't seem to be particularly popular/polished: the
> > example value for Elisp, for instance, sets up search across all symbols
> > (obarray), but subsequent navigation only works for commands, and only
> > ones documented in the manual.
>
> I don't think we should be too bothered about that: once we have
> replacements for all of those etags features, we could declare the
> originals obsolete and point to replacements, something we cannot do
> when the replacements are missing.  So I think we should install this.

Fair enough.

I'd still like to see someone working on a better suggested default 
config for it, but it's not a blocker.

> >   (cl-defmethod xref-backend-apropos ((_backend (eql 'etags)) pattern)
> > -  (etags--xref-find-definitions (xref-apropos-regexp pattern) t))
> > +  (let ((regexp (xref-apropos-regexp pattern)))
> > +    (nconc
> > +     (etags--xref-find-definitions regexp t)
> > +     (etags--xref-apropos-additional regexp))))
>
> I'm not sure I understand why is this specific to the etags backend.
> The spec seems to be more general, and xref-find-apropos is not
> specific to etags, right?

If as you say above it is for feature parity with 'M-x tags-apropos', 
then the previously sent patch should be enough.

We are honoring the etags-specific variable 
(tags-apropos-additional-actions), so the result should be specific to 
the etags backend.

> We'd also need a defcustom, similar to tags-apropos-additional-actions.

Could we extend it to be the feature of 'M-x xref-find-apropos' in 
general rather than the etags backend? It's possible, if we see specific 
user demand for it.

Here are considerations why I chose the other route:

- As I said, the existing etags feature is not very polished. To bring 
it into the Xref API proper, we'd have to redesign it somehow, and since 
the feature doesn't seem to scratch any of my personal itches, I need 
feature requests to narrow down the design space.

- It has been somewhat of a rule that backend methods don't change 
behavior based on some global user option, both in project.el and xref. 
Rather, each backend is more free to do its own thing and have 
backend-specific options for configuring. We can break this rule, of 
course, when presented with good reasons for it.

- It's hard for me to say whether third-party backends will want this 
behavior added to their backends unconditionally. But even when we're 
talking about the elisp backend... do we? Want it there?

- We don't need to make this choice now. It will be easy to install the 
already provided patch and then possibly extend the feature to all 
backends at some later point.