; Reword bits of ElDoc internal documentation

* lisp/emacs-lisp/eldoc.el (eldoc--invoke-strategy): Rewrite docstring.
(eldoc--invoke-strategy): Fix formatting and rewrite comments

diff --git a/lisp/emacs-lisp/eldoc.el b/lisp/emacs-lisp/eldoc.el
index 510dff9ed0bce0509efdaf0f6a54f5eee3d4c747..5741c524d646c522b63093f7cb727f7f294acff3 100644 (file)
--- a/lisp/emacs-lisp/eldoc.el
+++ b/lisp/emacs-lisp/eldoc.el
@@ -664,75 +664,75 @@ have the following values:
   "Invoke `eldoc-documentation-strategy' function.
 
 That function's job is to run the `eldoc-documentation-functions'
-special hook, using the `run-hook' family of functions.  The way
-we invoke it here happens in a way strategy function can itself
-call `eldoc--make-callback' to produce values to give to the
-elements of the special hook `eldoc-documentation-functions'.
-
-For each element of `eldoc-documentation-functions' invoked a
-corresponding call to `eldoc--make-callback' must be made.  See
-docstring of `eldoc--make-callback' for the types of callback
-that can be produced.
-
-If the strategy function does not use `eldoc--make-callback', it
-must find some alternate way to produce callbacks to feed to
-`eldoc-documentation-function', and those callbacks should
-endeavour to display the docstrings given to them."
-  (let* (;; how many docstrings callbaks have been
+special hook, using the `run-hook' family of functions.  ElDoc's
+built-in strategy functions play along with the
+`eldoc--make-callback' protocol, using it to produce callback to
+feed to the functgions of `eldoc-documentation-functions'.
+
+Other third-party strategy functions do not use
+`eldoc--make-callback'.  They must find some alternate way to
+produce callbacks to feed to `eldoc-documentation-function' and
+should endeavour to display the docstrings eventually produced."
+  (let* (;; How many callbacks have been created by the strategy
+         ;; fucntion and passed to elements of
+         ;; `eldoc-documentation-functions'.
          (howmany 0)
-         ;; how many calls to callbacks we're waiting on. Used by
-         ;; `:patient'.
+         ;; How many calls to callbacks we're still waiting on.  Used
+         ;; by `:patient'.
          (want 0)
-         ;; how many doc strings and corresponding options have been
-         ;; registered it.
+         ;; The doc strings and corresponding options registered so
+         ;; far.
          (docs-registered '()))
-          (cl-labels
-              ((register-doc (pos string plist)
-                (when (and string (> (length string) 0))
-                  (push (cons pos (cons string plist)) docs-registered)))
-               (display-doc ()
-                (eldoc--handle-docs
-                 (mapcar #'cdr
-                         (setq docs-registered
-                               (sort docs-registered
-                                     (lambda (a b) (< (car a) (car b))))))))
-               (make-callback (method)
-                (let ((pos (prog1 howmany (cl-incf howmany))))
-                  (cl-ecase method
-                    (:enthusiast
-                     (lambda (string &rest plist)
-                       (when (and string (cl-loop for (p) in docs-registered
-                                                  never (< p pos)))
-                         (setq docs-registered '())
-                         (register-doc pos string plist)
-                         (when (and (timerp eldoc--enthusiasm-curbing-timer)
-                                    (memq eldoc--enthusiasm-curbing-timer
-                                          timer-list))
-                           (cancel-timer eldoc--enthusiasm-curbing-timer))
-                         (setq eldoc--enthusiasm-curbing-timer
-                               (run-at-time (unless (zerop pos) 0.3)
-                                            nil #'display-doc)))
-                       t))
-                    (:patient
-                     (cl-incf want)
-                     (lambda (string &rest plist)
-                       (register-doc pos string plist)
-                       (when (zerop (cl-decf want)) (display-doc))
-                       t))
-                    (:eager
-                     (lambda (string &rest plist)
-                       (register-doc pos string plist)
-                       (display-doc)
-                       t))))))
-            (let* ((eldoc--make-callback #'make-callback)
-                   (res (funcall eldoc-documentation-strategy)))
-              ;; Observe the old and the new protocol:
-              (cond (;; Old protocol: got string, output immediately;
-                     (stringp res) (register-doc 0 res nil) (display-doc))
-                    (;; Old protocol: got nil, clear the echo area;
-                     (null res) (eldoc--message nil))
-                    (;; New protocol: trust callback will be called;
-                     t))))))
+    (cl-labels
+        ((register-doc
+          (pos string plist)
+          (when (and string (> (length string) 0))
+            (push (cons pos (cons string plist)) docs-registered)))
+         (display-doc
+          ()
+          (eldoc--handle-docs
+           (mapcar #'cdr
+                   (setq docs-registered
+                         (sort docs-registered
+                               (lambda (a b) (< (car a) (car b))))))))
+         (make-callback
+          (method)
+          (let ((pos (prog1 howmany (cl-incf howmany))))
+            (cl-ecase method
+              (:enthusiast
+               (lambda (string &rest plist)
+                 (when (and string (cl-loop for (p) in docs-registered
+                                            never (< p pos)))
+                   (setq docs-registered '())
+                   (register-doc pos string plist)
+                   (when (and (timerp eldoc--enthusiasm-curbing-timer)
+                              (memq eldoc--enthusiasm-curbing-timer
+                                    timer-list))
+                     (cancel-timer eldoc--enthusiasm-curbing-timer))
+                   (setq eldoc--enthusiasm-curbing-timer
+                         (run-at-time (unless (zerop pos) 0.3)
+                                      nil #'display-doc)))
+                 t))
+              (:patient
+               (cl-incf want)
+               (lambda (string &rest plist)
+                 (register-doc pos string plist)
+                 (when (zerop (cl-decf want)) (display-doc))
+                 t))
+              (:eager
+               (lambda (string &rest plist)
+                 (register-doc pos string plist)
+                 (display-doc)
+                 t))))))
+      (let* ((eldoc--make-callback #'make-callback)
+             (res (funcall eldoc-documentation-strategy)))
+        ;; Observe the old and the new protocol:
+        (cond (;; Old protocol: got string, output immediately;
+               (stringp res) (register-doc 0 res nil) (display-doc))
+              (;; Old protocol: got nil, clear the echo area;
+               (null res) (eldoc--message nil))
+              (;; New protocol: trust callback will be called;
+               t))))))
 
 (defun eldoc-print-current-symbol-info (&optional interactive)
   "Document thing at point."