Adjust Eldoc documentation after Eli's review

* etc/NEWS (Eldoc): Adjust paragraphs.

* lisp/emacs-lisp/eldoc.el (eldoc-prefer-doc-buffer): Adjust
docstring.
(eldoc--enthusiasm-curbing-timer, eldoc-documentation-strategy)
(eldoc-documentation-functions): Adjust docstring.
(eldoc--handle-docs): Adjust comments.
(eldoc--documentation-compose-1): New helper.
(eldoc-documentation-compose)
(eldoc-documentation-compose-eagerly): Use it.
(eldoc-print-current-symbol-info): Adjust comments.

1 files changed, 14 insertions, 6 deletions

diff --git a/etc/NEWS b/etc/NEWS
index f5b9e5ed152..125457c609b 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -247,17 +247,25 @@ supplied error message.
 +++
 ** ElDoc
 
-*** New hook 'eldoc-documentation-functions' to be used for registering
-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'.
+*** New hook 'eldoc-documentation-functions' to be used for
+registering doc string functions.  These functions don't need to
+produce the doc string right away, they may arrange for it to be
+produced asynchronously.  The results of all doc string functions
+accessible to the user through the existing single function hook
+'eldoc-documentation-strategy.
 
 *** 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
+the results of 'eldoc-documentation-functions' in various ways, even
+if some of those functions are sychronous and some asynchchronous.
+The user option replaces 'eldoc-documentation-function', which is now
 obsolete.
 
+*** The user option 'eldoc-echo-area-use-multiline-p' is now handled
+by the Eldoc library itself.  Functions in
+'eldoc-documentation-functions' don't need to worry about consulting
+it when producing a doc string.
+
 ** Eshell
 
 ---