From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: "Charles A. Roelli" Newsgroups: gmane.emacs.bugs Subject: bug#27230: eldoc doc Date: Sun, 25 Jun 2017 21:47:46 +0200 Message-ID: References: <282e174a-e9c0-6bec-32f5-ed9d772e5e1d@yandex.ru> <83efu8ta6n.fsf@gnu.org> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="------------2FA1671CC8167200B143813B" X-Trace: blaine.gmane.org 1498420097 32275 195.159.176.226 (25 Jun 2017 19:48:17 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sun, 25 Jun 2017 19:48:17 +0000 (UTC) User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:45.0) Gecko/20100101 Thunderbird/45.8.0 Cc: dgutov@yandex.ru, 27230@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Jun 25 21:48:11 2017 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dPDVz-00081C-2Y for geb-bug-gnu-emacs@m.gmane.org; Sun, 25 Jun 2017 21:48:11 +0200 Original-Received: from localhost ([::1]:43633 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dPDW4-0003Ah-9X for geb-bug-gnu-emacs@m.gmane.org; Sun, 25 Jun 2017 15:48:16 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:51595) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dPDVw-00037K-9l for bug-gnu-emacs@gnu.org; Sun, 25 Jun 2017 15:48:11 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dPDVt-0004Nt-55 for bug-gnu-emacs@gnu.org; Sun, 25 Jun 2017 15:48:08 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:34973) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1dPDVt-0004NX-0a for bug-gnu-emacs@gnu.org; Sun, 25 Jun 2017 15:48:05 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1dPDVr-0003GR-0q for bug-gnu-emacs@gnu.org; Sun, 25 Jun 2017 15:48:04 -0400 X-Loop: help-debbugs@gnu.org Resent-From: "Charles A. Roelli" Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 25 Jun 2017 19:48:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 27230 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 27230-submit@debbugs.gnu.org id=B27230.149842008112539 (code B ref 27230); Sun, 25 Jun 2017 19:48:02 +0000 Original-Received: (at 27230) by debbugs.gnu.org; 25 Jun 2017 19:48:01 +0000 Original-Received: from localhost ([127.0.0.1]:37650 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dPDVo-0003GB-P5 for submit@debbugs.gnu.org; Sun, 25 Jun 2017 15:48:01 -0400 Original-Received: from sinyavsky.aurox.ch ([37.35.109.145]:49916) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dPDVl-0003Fv-Jt for 27230@debbugs.gnu.org; Sun, 25 Jun 2017 15:47:58 -0400 Original-Received: from sinyavsky.aurox.ch (sinyavsky.aurox.ch [127.0.0.1]) by sinyavsky.aurox.ch (Postfix) with ESMTP id C900422483 for <27230@debbugs.gnu.org>; Sun, 25 Jun 2017 19:42:55 +0000 (UTC) Authentication-Results: sinyavsky.aurox.ch (amavisd-new); dkim=pass (1024-bit key) reason="pass (just generated, assumed good)" header.d=aurox.ch DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=aurox.ch; h= content-type:content-type:in-reply-to:mime-version:user-agent :date:date:message-id:from:from:references:to:subject:subject; s=dkim; t=1498419772; x=1499283773; bh=sLsfLx0BiGiNuxf1J/sLI3Xc +VEezMEyiCYRxtlc0nc=; b=ePba/tsPr14eK3JMADhQY4qpZc02s+tvl6ZnVy3L 8DOCJLHY+X9nQqGRYppdwc/td2WQ0HH1mEQa7s2fYchQ8xUTAv9QsTCWGVbhfu/E o1Y70+CFPPNitvqyDJUt7Q1jBPq9TwXFwXoYOX11HMsLWcKoA5BYtk/Vdnf6MOOi WIQ= X-Virus-Scanned: Debian amavisd-new at test.virtualizor.com Original-Received: from sinyavsky.aurox.ch ([127.0.0.1]) by sinyavsky.aurox.ch (sinyavsky.aurox.ch [127.0.0.1]) (amavisd-new, port 10026) with ESMTP id vZ-KgUvaqfgP for <27230@debbugs.gnu.org>; Sun, 25 Jun 2017 19:42:52 +0000 (UTC) Original-Received: from [192.168.1.121] (125.85.192.178.dynamic.wline.res.cust.swisscom.ch [178.192.85.125]) by sinyavsky.aurox.ch (Postfix) with ESMTPSA id 26E8522454; Sun, 25 Jun 2017 19:42:52 +0000 (UTC) In-Reply-To: <83efu8ta6n.fsf@gnu.org> X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:133900 Archived-At: This is a multi-part message in MIME format. --------------2FA1671CC8167200B143813B Content-Type: text/plain; charset=windows-1252; format=flowed Content-Transfer-Encoding: 7bit Thanks for the quick review! Revised patch is attached. On 25/06/2017 16:26, Eli Zaretskii wrote: >> From: "Charles A. Roelli" >> 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. --------------2FA1671CC8167200B143813B Content-Type: text/x-patch; name="0001-ElDoc-add-docstrings-and-minor-refactoring-v2.patch" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename*0="0001-ElDoc-add-docstrings-and-minor-refactoring-v2.patch" >From 18fe8d8a80be5966c4b9141afc4fc83748c85c9f Mon Sep 17 00:00:00 2001 From: Charles A. Roelli 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)))) (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)))) @@ -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 --------------2FA1671CC8167200B143813B--