From: "Charles A. Roelli" <charles@aurox.ch>
To: Eli Zaretskii <eliz@gnu.org>
Cc: dgutov@yandex.ru, 27230@debbugs.gnu.org
Subject: bug#27230: eldoc doc
Date: Sun, 25 Jun 2017 21:47:46 +0200 [thread overview]
Message-ID: <db8d2b72-d9a8-dc97-942a-960dbe744dcc@aurox.ch> (raw)
In-Reply-To: <83efu8ta6n.fsf@gnu.org>
[-- Attachment #1: Type: text/plain, Size: 2938 bytes --]
Thanks for the quick review! Revised patch is attached.
On 25/06/2017 16:26, Eli Zaretskii wrote:
>> From: "Charles A. Roelli" <charles@aurox.ch>
>> Date: Sun, 25 Jun 2017 11:14:23 +0200
>>
>> Here's a doc patch for ElDoc, with some minor readability fixes.
> Thanks. Please allow me a few comments below.
>
>> -(defun eldoc-message (&rest args)
>> +(defun eldoc-message (&optional format-string &rest args)
>> + "Store and display the given message.
> The first line of a doc string should ideally mention the arguments.
"Store and possibly display FORMAT-STRING formatted with ARGS.
FORMAT-STRING (or nil, if not given) is stored in
`eldoc-last-message'. If ARGS are given, FORMAT-STRING is first
formatted through `format-message'.
If `eldoc-last-message' is non-nil, display it using
`eldoc-message-function'. If it is nil, clear the echo area if
there was recently a message from ElDoc there.
Return `eldoc-last-message'."
>
>> +FORMAT-STRING and ARGS, if given, are passed to `format-message',
>> +the output of which is stored in `eldoc-last-message'.
> This leaves me wondering what happens if no arguments are supplied.
See above.
>
>> (defun eldoc--message-command-p (command)
>> + "Non-nil if COMMAND is a command in `eldoc-message-commands'."
> "Return non-nil if ...". The way you wrote it is appropriate for a
> variable, not for a function.
Fixed.
>
>> (defun eldoc-pre-command-refresh-echo-area ()
>> + "Reprint `eldoc-last-message' to the echo area."
> Are you sure about the "to" part? I'd say "in" sounds more correct.
Agreed, it's fixed.
>
>> (defun eldoc-display-message-p ()
>> + "Non-nil when appropriate to display an ElDoc message."
> "Return non-nil"
Fixed.
>
>> (defun eldoc-display-message-no-interference-p ()
>> + "Nil when displaying an ElDoc message would cause interference
>> +with other features."
> Likewise. Also, the first line of a doc string should be a complete
> sentence.
Fixed.
>
>> (defun eldoc-print-current-symbol-info ()
>> + "Print the output of `eldoc-documentation-function'."
> "Print the output" sounds confusing. How about this instead:
>
> Print the text produced by `eldoc-documentation-function'.
Fixed.
>
>> (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.
> First line not a complete sentence again.
How about this?
"Combine PREFIX and DOC, and shorten the result to fit in the echo area.
When PREFIX is a symbol, propertize its symbol name with FACE
before combining it with DOC. If FACE is not provided, just
apply the nil face.
See also: `eldoc-echo-area-use-multiline-p'."
>> +When PREFIX is a symbol, apply FACE to it before concatenating.
> But FACE is optional, so what if it isn't given?
See above.
>
> Thanks for working on this.
Thanks again for your advice.
[-- Attachment #2: 0001-ElDoc-add-docstrings-and-minor-refactoring-v2.patch --]
[-- Type: text/x-patch, Size: 8336 bytes --]
From 18fe8d8a80be5966c4b9141afc4fc83748c85c9f 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 | 57 +++++++++++++++++++++++++++++++++++++---------
1 files changed, 46 insertions(+), 11 deletions(-)
diff --git a/lisp/emacs-lisp/eldoc.el b/lisp/emacs-lisp/eldoc.el
index a05bd7c..9b4a2d4 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,27 @@ 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 possibly display FORMAT-STRING formatted with ARGS.
+
+FORMAT-STRING (or nil, if not given) is stored in
+`eldoc-last-message'. If ARGS are given, FORMAT-STRING is first
+formatted through `format-message'.
+
+If `eldoc-last-message' is non-nil, display it using
+`eldoc-message-function'. If it is nil, clear the echo area if
+there was recently a message from ElDoc there.
+
+Return `eldoc-last-message'."
(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 +308,7 @@ eldoc-message
eldoc-last-message)
(defun eldoc--message-command-p (command)
+ "Return non-nil if COMMAND is in `eldoc-message-commands'."
(and (symbolp command)
(intern-soft (symbol-name command) eldoc-message-commands)))
@@ -299,6 +319,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' in 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 +331,7 @@ eldoc-pre-command-refresh-echo-area
;; Decide whether now is a good time to display a message.
(defun eldoc-display-message-p ()
+ "Return non-nil when it is 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 +344,7 @@ 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 ()
+ "Return nil if displaying a message would cause interference."
(not (or executing-kbd-macro (bound-and-true-p edebug-active))))
\f
@@ -347,6 +370,7 @@ eldoc-documentation-function
return any documentation.")
(defun eldoc-print-current-symbol-info ()
+ "Print the text produced by `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 +385,13 @@ 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)
+ "Combine PREFIX and DOC, and shorten the result to fit in the echo area.
+
+When PREFIX is a symbol, propertize its symbol name with FACE
+before combining it with DOC. If FACE is not provided, just
+apply the nil face.
+
+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 +421,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 +453,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
next prev parent reply other threads:[~2017-06-25 19:47 UTC|newest]
Thread overview: 22+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-06-04 10:38 bug#27230: eldoc doc Charles A. Roelli
2017-06-05 22:08 ` Dmitry Gutov
2017-06-06 18:33 ` Charles A. Roelli
2017-06-06 20:19 ` Dmitry Gutov
2017-06-25 9:14 ` Charles A. Roelli
2017-06-25 14:26 ` Eli Zaretskii
2017-06-25 19:47 ` Charles A. Roelli [this message]
2017-06-26 1:04 ` Dmitry Gutov
2017-06-27 19:51 ` Charles A. Roelli
2017-06-27 23:50 ` Dmitry Gutov
2017-06-28 19:16 ` Charles A. Roelli
2017-07-22 8:11 ` Eli Zaretskii
2017-09-14 11:47 ` Peder O. Klingenberg
2017-09-14 12:02 ` Dmitry Gutov
2017-09-14 19:39 ` Charles A. Roelli
2017-09-14 22:03 ` Dmitry Gutov
2017-09-19 20:02 ` Charles A. Roelli
2017-09-20 18:12 ` Charles A. Roelli
2017-09-21 14:23 ` Dmitry Gutov
2017-09-21 18:33 ` Charles A. Roelli
2017-09-21 23:05 ` Dmitry Gutov
2017-09-25 23:26 ` Dmitry Gutov
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=db8d2b72-d9a8-dc97-942a-960dbe744dcc@aurox.ch \
--to=charles@aurox.ch \
--cc=27230@debbugs.gnu.org \
--cc=dgutov@yandex.ru \
--cc=eliz@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).