'xref' should be documented

'xref' should be documented

[Eli Zaretskii]

I think it's high time we had the xref facilities documented, both in
the user manual and in the ELisp manual.  It's not good for such a
high-profile feature to remain undocumented.

The minimal documentation in etc/NEWS is less useful than it could be,
and should IMO be improved ASAP.  Here are some comments on the
current text in NEWS, which I hope will be useful for improving it:

First, the style is wrong: it is written as a description of how the
old bindings were changed into the new ones, instead of describing the
new state.  For example, this text:

   Hence, `tags-loop-continue' is unbound.  `xref-pop-marker-stack'
   replaces `pop-tag-mark', but uses an easier binding, which is now
   unoccupied (`M-,').

could be significantly improved if it simply said something like

   `M-.' is now bound to `xref-find-definitions' instead of
   `find-tag', and `M-,' is bound to `xref-pop-marker-stack' instead
   of `tags-loop-continue'.

Second, NEWS doesn't mention `xref-etags-mode', which it should, since
NEWS should say how to get back the previous behavior.  It should also
have more explicit information about getting all of the old behavior
back, by listing key bindings that would accomplish that, but since
the key bindings for `xref-find-definitions-other-window' etc. are not
mentioned, the user will have to work harder than necessary to figure
this out.

Finally, I think NEWS should also include (in a separate section)
information about Lisp-level facilities, of interest to Lisp
programmers who'd want to code their own back-end.  This is currently
completely uncovered.

TIA

Re: 'xref' should be documented

[Dmitry Gutov]

On 04/26/2015 05:57 PM, Eli Zaretskii wrote:
> I think it's high time we had the xref facilities documented, both in
> the user manual and in the ELisp manual.  It's not good for such a
> high-profile feature to remain undocumented.

Thanks for the reminder, but I'd rather the dust settles further around 
it, first.

Re: 'xref' should be documented

[Eli Zaretskii]

> Date: Tue, 28 Apr 2015 02:49:10 +0300
> From: Dmitry Gutov <dgutov@yandex.ru>
> 
>     I think it's high time we had the xref facilities documented, both in
>     the user manual and in the ELisp manual.  It's not good for such a
>     high-profile feature to remain undocumented.
> 
> Thanks for the reminder, but I'd rather the dust settles further around it, first.

I think this is a mistake.  There are definitely parts of xref that
are already stable and won't change -- these could be documented
already.  There are many shades of gray between having zero
documentation and having a 100% complete one.  Right now we are very
close to zero, which I think is not justified.  We could add the parts
that are still debated as they settle.