'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