bug#27230: eldoc doc

["Charles A. Roelli" <charles@aurox.ch>]

[-- Attachment #1: Type: text/plain, Size: 1162 bytes --]

Here's a doc patch for ElDoc, with some minor readability fixes.

I'm unsure how to improve the doc for globalized minor modes, so I'll
leave that for another time.


On 06/06/2017 22:19, Dmitry Gutov wrote:
> On 6/6/17 9:33 PM, Charles A. Roelli wrote:
>> I'm confused about how the command `define-globalized-minor-mode'
>> defines will handle buffers that already have the minor mode turned
>> on.
>
> Indeed, the docstring is a bit ambiguous.
>
> Maybe you want to improve the documentation of the said function, or 
> the auto-generated docstring that it puts on the created minor modes.
>
>> Say buffers A and B have simple `eldoc-mode' switched on, and
>> buffers C and D don't (and global-eldoc-mode is off).  If I then
>> switch global-eldoc-mode on, is every buffer's value of eldoc-mode
>> now /on/, or do the values get toggled instead (leaving A and B off, C
>> and D on)?
>
> Not toggled, of course. On everywhere (where appropriate).
>
>> And after that, if I toggle global-eldoc-mode off again,
>> are the previous values remembered and restored, or does every buffer
>> now have eldoc-mode switched off?
>
> Not remembered, no. Off everywhere.


[-- Attachment #2: 0001-ElDoc-add-docstrings-and-minor-refactoring.patch --]
[-- Type: text/x-patch, Size: 8140 bytes --]

From 744b20db5524b32302e9cd90cb71dcaec580430e Mon Sep 17 00:00:00 2001
From: Charles A. Roelli <charles@aurox.ch>
Date: Thu, 22 Jun 2017 21:04:09 +0200
Subject: [PATCH] ElDoc: add docstrings and minor refactoring

* lisp/emacs-lisp/eldoc.el (eldoc-edit-message-commands): Add
docstring.
(turn-on-eldoc-mode): Fix capitalization.
(eldoc--supported-p): Add docstring.
(eldoc-schedule-timer): Add docstring and use
'eldoc--supported-p'.
(eldoc-message): Add docstring and make calling convention
clearer.
(eldoc--message-command-p):
(eldoc-pre-command-refresh-echo-area):
(eldoc-display-message-p):
(eldoc-display-message-no-interference-p):
(eldoc-print-current-symbol-info):
(eldoc-docstring-format-sym-doc):
(eldoc-add-command, eldoc-add-command-completions):
(eldoc-remove-command, eldoc-remove-command-completions):
Add docstring.
---
 lisp/emacs-lisp/eldoc.el |   53 ++++++++++++++++++++++++++++++++++++---------
 1 files changed, 42 insertions(+), 11 deletions(-)

diff --git a/lisp/emacs-lisp/eldoc.el b/lisp/emacs-lisp/eldoc.el
index a05bd7c..2d8e029 100644
--- a/lisp/emacs-lisp/eldoc.el
+++ b/lisp/emacs-lisp/eldoc.el
@@ -160,6 +160,10 @@ eldoc-message-function
 It should receive the same arguments as `message'.")
 
 (defun eldoc-edit-message-commands ()
+  "Return an obarray containing common editing commands.
+
+When `eldoc-print-after-edit' is non-nil, ElDoc messages are only
+printed after commands contained in this obarray."
   (let ((cmds (make-vector 31 0))
 	(re (regexp-opt '("delete" "insert" "edit" "electric" "newline"))))
     (mapatoms (lambda (s)
@@ -211,16 +215,21 @@ global-eldoc-mode
 
 ;;;###autoload
 (defun turn-on-eldoc-mode ()
-  "Turn on `eldoc-mode' if the buffer has eldoc support enabled.
+  "Turn on `eldoc-mode' if the buffer has ElDoc support enabled.
 See `eldoc-documentation-function' for more detail."
   (when (eldoc--supported-p)
     (eldoc-mode 1)))
 
 (defun eldoc--supported-p ()
+  "Non-nil if an ElDoc function is set for this buffer."
   (not (memq eldoc-documentation-function '(nil ignore))))
 
 \f
 (defun eldoc-schedule-timer ()
+  "Ensure `eldoc-timer' is running.
+
+If the user has changed `eldoc-idle-delay', update the timer to
+reflect the change."
   (or (and eldoc-timer
            (memq eldoc-timer timer-idle-list)) ;FIXME: Why?
       (setq eldoc-timer
@@ -229,8 +238,7 @@ eldoc-schedule-timer
 	     (lambda ()
                (when (or eldoc-mode
                          (and global-eldoc-mode
-                              (not (memq eldoc-documentation-function
-                                         '(nil ignore)))))
+                              (eldoc--supported-p)))
                  (eldoc-print-current-symbol-info))))))
 
   ;; If user has changed the idle delay, update the timer.
@@ -268,16 +276,23 @@ eldoc-minibuffer-message
           (force-mode-line-update)))
     (apply 'message format-string args)))
 
-(defun eldoc-message (&rest args)
+(defun eldoc-message (&optional format-string &rest args)
+  "Store and display the given message.
+
+FORMAT-STRING and ARGS, if given, are passed to `format-message',
+the output of which is stored in `eldoc-last-message'.
+
+`eldoc-last-message' is then displayed (using
+`eldoc-message-function') and returned."
   (let ((omessage eldoc-last-message))
     (setq eldoc-last-message
-	  (cond ((eq (car args) eldoc-last-message) eldoc-last-message)
-		((null (car args)) nil)
+	  (cond ((eq format-string eldoc-last-message) eldoc-last-message)
+		((null format-string) nil)
 		;; If only one arg, no formatting to do, so put it in
 		;; eldoc-last-message so eq test above might succeed on
 		;; subsequent calls.
-		((null (cdr args)) (car args))
-		(t (apply #'format-message args))))
+		((null args) format-string)
+		(t (apply #'format-message format-string args))))
     ;; In emacs 19.29 and later, and XEmacs 19.13 and later, all messages
     ;; are recorded in a log.  Do not put eldoc messages in that log since
     ;; they are Legion.
@@ -289,6 +304,7 @@ eldoc-message
   eldoc-last-message)
 
 (defun eldoc--message-command-p (command)
+  "Non-nil if COMMAND is a command in `eldoc-message-commands'."
   (and (symbolp command)
        (intern-soft (symbol-name command) eldoc-message-commands)))
 
@@ -299,6 +315,7 @@ eldoc--message-command-p
 ;; before the next command executes, which does away with the flicker.
 ;; This doesn't seem to be required for Emacs 19.28 and earlier.
 (defun eldoc-pre-command-refresh-echo-area ()
+  "Reprint `eldoc-last-message' to the echo area."
   (and eldoc-last-message
        (not (minibufferp))      ;We don't use the echo area when in minibuffer.
        (if (and (eldoc-display-message-no-interference-p)
@@ -310,6 +327,7 @@ eldoc-pre-command-refresh-echo-area
 
 ;; Decide whether now is a good time to display a message.
 (defun eldoc-display-message-p ()
+  "Non-nil when appropriate to display an ElDoc message."
   (and (eldoc-display-message-no-interference-p)
        ;; If this-command is non-nil while running via an idle
        ;; timer, we're still in the middle of executing a command,
@@ -322,6 +340,8 @@ eldoc-display-message-p
 ;; Check various conditions about the current environment that might make
 ;; it undesirable to print eldoc messages right this instant.
 (defun eldoc-display-message-no-interference-p ()
+  "Nil when displaying an ElDoc message would cause interference
+with other features."
   (not (or executing-kbd-macro (bound-and-true-p edebug-active))))
 
 \f
@@ -347,6 +367,7 @@ eldoc-documentation-function
 return any documentation.")
 
 (defun eldoc-print-current-symbol-info ()
+  "Print the output of `eldoc-documentation-function'."
   ;; This is run from post-command-hook or some idle timer thing,
   ;; so we need to be careful that errors aren't ignored.
   (with-demoted-errors "eldoc error: %s"
@@ -361,6 +382,12 @@ eldoc-print-current-symbol-info
 ;; truncated or eliminated entirely from the output to make room for the
 ;; description.
 (defun eldoc-docstring-format-sym-doc (prefix doc &optional face)
+  "Concatenate PREFIX and DOC, returning the largest part of the
+resultant string that can fit in the minibuffer window.
+
+When PREFIX is a symbol, apply FACE to it before concatenating.
+
+See also: `eldoc-echo-area-use-multiline-p'."
   (when (symbolp prefix)
     (setq prefix (concat (propertize (symbol-name prefix) 'face face) ": ")))
   (let* ((ea-multi eldoc-echo-area-use-multiline-p)
@@ -390,22 +417,26 @@ eldoc-docstring-format-sym-doc
 ;; These functions do display-command table management.
 
 (defun eldoc-add-command (&rest cmds)
+  "Add each of CMDS to the obarray `eldoc-message-commands'."
   (dolist (name cmds)
     (and (symbolp name)
          (setq name (symbol-name name)))
     (set (intern name eldoc-message-commands) t)))
 
 (defun eldoc-add-command-completions (&rest names)
+  "Pass every prefix completion of NAMES to `eldoc-add-command'."
   (dolist (name names)
     (apply #'eldoc-add-command (all-completions name obarray 'commandp))))
 
 (defun eldoc-remove-command (&rest cmds)
+  "Remove each of CMDS from the obarray `eldoc-message-commands'."
   (dolist (name cmds)
     (and (symbolp name)
          (setq name (symbol-name name)))
     (unintern name eldoc-message-commands)))
 
 (defun eldoc-remove-command-completions (&rest names)
+  "Pass every prefix completion of NAMES to `eldoc-remove-command'."
   (dolist (name names)
     (apply #'eldoc-remove-command
            (all-completions name eldoc-message-commands))))
@@ -418,9 +449,9 @@ eldoc-remove-command-completions
  "down-list" "end-of-" "exchange-point-and-mark" "forward-" "goto-"
  "handle-select-window" "indent-for-tab-command" "left-" "mark-page"
  "mark-paragraph" "mouse-set-point" "move-" "move-beginning-of-"
- "move-end-of-" "newline" "next-" "other-window" "pop-global-mark" "previous-"
- "recenter" "right-" "scroll-" "self-insert-command" "split-window-"
- "up-list")
+ "move-end-of-" "newline" "next-" "other-window" "pop-global-mark"
+ "previous-" "recenter" "right-" "scroll-" "self-insert-command"
+ "split-window-" "up-list")
 
 (provide 'eldoc)
 
-- 
1.7.4.4