scratch/eldoc-async b8656e2 1/5: Update manual and NEWS for new Eldoc features

[João Távora]

branch: scratch/eldoc-async
commit b8656e25f7d5551dad2169d273b9381f68bdeb97
Author: João Távora <joaotavora@gmail.com>
Commit: João Távora <joaotavora@gmail.com>

    Update manual and NEWS for new Eldoc features
    
    * doc/emacs/programs.texi (Lisp Doc): Mention
    eldoc-documentation-strategy.
    
    * doc/lispref/modes.texi (Major Mode Conventions): Mention
    eldoc-documentation-functions.
    
    * etc/NEWS: Mention eldoc-documentation-strategy.
    
    * lisp/emacs-lisp/eldoc.el (eldoc-documentation-functions):
    Improve docstring.
---
 doc/emacs/programs.texi  | 10 ++++++----
 doc/lispref/modes.texi   |  7 ++++---
 etc/NEWS                 |  8 +++++---
 lisp/emacs-lisp/eldoc.el | 27 ++++++++++++++++-----------
 4 files changed, 31 insertions(+), 21 deletions(-)

diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index 865a3a6..2757c84 100644
--- a/doc/emacs/programs.texi
+++ b/doc/emacs/programs.texi
@@ -1273,17 +1273,19 @@ Eldoc mode, which is turned on by default, and affects 
buffers whose
 major mode sets the variables described below.  Use @w{@kbd{M-x
 global-eldoc-mode}} to turn it off globally.
 
-@vindex eldoc-documentation-function
+@vindex eldoc-documentation-strategy
 @vindex eldoc-documentation-functions
   These variables can be used to configure ElDoc mode:
 
 @table @code
-@item eldoc-documentation-function
+@item eldoc-documentation-strategy
 This variable holds the function which is used to retrieve
 documentation for the item at point from the functions in the hook
 @code{eldoc-documentation-functions}.  By default,
-@code{eldoc-documentation-function} returns the first documentation
-string produced by the @code{eldoc-documentation-functions} hook.
+@code{eldoc-documentation-strategy} returns the first documentation
+string produced by the @code{eldoc-documentation-functions} hook, but
+it may be customized to compose those functions' results in other
+ways.
 
 @item eldoc-documentation-functions
 This abnormal hook holds documentation functions.  It acts as a
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index eaee56f..17e9607 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -469,9 +469,10 @@ variable @code{imenu-generic-expression}, for the two 
variables
 @code{imenu-create-index-function} (@pxref{Imenu}).
 
 @item
-The mode can specify a local value for
-@code{eldoc-documentation-function} to tell ElDoc mode how to handle
-this mode.
+The mode can tell Eldoc mode how to retrieve different types of
+documentation for whatever is at point, by adding one or more
+buffer-local entries to the special hook
+@code{eldoc-documentation-functions}.
 
 @item
 The mode can specify how to complete various keywords by adding one or
diff --git a/etc/NEWS b/etc/NEWS
index 36ef350..7be06db 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -199,9 +199,11 @@ doc string functions.  This makes the results of all doc 
string
 functions accessible to the user through the existing single function hook
 'eldoc-documentation-function'.
 
-*** 'eldoc-documentation-function' is now a user option.
-Modes should use the new hook instead of this user option to register
-their backends.
+*** New user option 'eldoc-documentation-strategy'
+The built-in choices available for this user option let users compose
+the results of 'eldoc-documentation-functions' in various ways.  The
+user option replaces 'eldoc-documentation-function', which is now
+obsolete.
 
 ** Eshell
 
diff --git a/lisp/emacs-lisp/eldoc.el b/lisp/emacs-lisp/eldoc.el
index ea6f619..fe985e9 100644
--- a/lisp/emacs-lisp/eldoc.el
+++ b/lisp/emacs-lisp/eldoc.el
@@ -367,17 +367,22 @@ A doc string is typically relevant if point is on a 
function-like
 name, inside its arg list, or on any object with some associated
 information.
 
-Each hook function should accept at least one argument CALLBACK
-and decide whether to display a doc short string about the
-context around point.  If the decision and the doc string can be
-produced quickly, the hook function can ignore CALLBACK and
-immediately return the doc string.  It may also return nil if
-there's no doc appropriate for the context.  Otherwise, if the
-computation of said docstring is expensive or can't be performed
-directly, the hook function should return a non-nil, non-string
-value and then arrange for CALLBACK to be called at a later time.
-
-That call is expected to pass CALLBACK a single argument
+Each hook function is called with at least one argument CALLBACK
+and decides whether to display a doc short string about the
+context around point.  If that decision can be taken quickly, the
+hook function may ignore CALLBACK and immediately return either
+the doc string or nil if there's no doc appropriate for the
+context.  Otherwise, it should return a non-string, non-nil value
+and arrange for CALLBACK to be called later.
+
+In particular, if the computation of said docstring (or the
+decision as to whether there is documentation at all) is
+expensive or can't be performed directly, the hook function
+should return a non-nil, non-string value and arrange for
+CALLBACK to be called at a later time, using asynchronous
+processes or other asynchronous mechanisms.
+
+However CALLBACK is called, it expects to be passed an argument
 DOCSTRING followed by an optional list of keyword-value pairs of
 the form (:KEY VALUE :KEY2 VALUE2...).  KEY can be: