Re: [Emacs-diffs] emacs-25 f8208b6: Document the user-level features of the Xref package

[Eli Zaretskii <eliz@gnu.org>]

> From: Stephen Leake <stephen_leake@stephe-leake.org>
> Cc: Eli Zaretskii <eliz@gnu.org>,  emacs-devel@gnu.org
> Date: Fri, 22 Jan 2016 01:40:04 -0600
> 
> Dmitry Gutov <dgutov@yandex.ru> writes:
> 
> > On 01/21/2016 10:19 PM, Stephen Leake wrote:
> >
> >> xref-find-apropos
> >>
> >>      This is just a search, not relying on any "cross reference"
> >>      information.
> >>
> >>      project-find-* provides the same functionality, so xref-find-apropos
> >>      can be removed (assuming every xref backend provides a project
> >>      backend).
> >
> > No, "apropos" lists the *definitions* matching a regexp. You won't get
> > that by simply using regexp-search.
> 
> The doc string says:
> 
>     Find all meaningful symbols that match PATTERN.
>     The argument has the same meaning as in ‘apropos’.

The doc string "needs work"™.  Welcome to the issue of doc strings of
quite a few commands introduced in Emacs 25.  Feel free to augment,
expand, improve, or even rewrite any of them, based on what the code
actually does.  Thanks in advance.

> I read that as "all occurances of the regexp"; I don't know what
> "meaningful" is supposed to mean here.
> 
> If it is supposed to find only definitions, the doc string should say
> so:
> 
>     Find the definitions of all symbols that match PATTERN.
>     PATTERN has the same meaning as in `apropos'.

The manual says:

     The command `C-M-.' (`xref-find-apropos') finds the definitions of
  one or more identifiers that match a specified regular expression.  It
  is just like `M-.' except that it does regexp matching of identifiers
  instead of matching symbol names as fixed strings.

> However, the etags implementation uses re-search-forward to find PATTERN
> in the tags files; that won't handle word lists as `apropos' does. So
> does that need to be fixed, or should we change the doc string further
> to say:
> 
>     Find the definitions of all symbols that match PATTERN (a regexp).

Good question.