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 11:14:23 +0200 Message-ID: References: <282e174a-e9c0-6bec-32f5-ed9d772e5e1d@yandex.ru> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="------------35029ED80AD546807560BEB5" X-Trace: blaine.gmane.org 1498382123 4724 195.159.176.226 (25 Jun 2017 09:15:23 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sun, 25 Jun 2017 09:15:23 +0000 (UTC) User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:45.0) Gecko/20100101 Thunderbird/45.8.0 To: Dmitry Gutov , 27230@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Jun 25 11:15:14 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 1dP3dM-0000Yv-Sf for geb-bug-gnu-emacs@m.gmane.org; Sun, 25 Jun 2017 11:15:09 +0200 Original-Received: from localhost ([::1]:41783 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dP3dR-0002g5-SX for geb-bug-gnu-emacs@m.gmane.org; Sun, 25 Jun 2017 05:15:13 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:59256) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dP3dL-0002dm-FZ for bug-gnu-emacs@gnu.org; Sun, 25 Jun 2017 05:15:09 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dP3dG-0003qT-F9 for bug-gnu-emacs@gnu.org; Sun, 25 Jun 2017 05:15:07 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:33613) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1dP3dG-0003qJ-72 for bug-gnu-emacs@gnu.org; Sun, 25 Jun 2017 05:15:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1dP3dF-0006Gy-SI for bug-gnu-emacs@gnu.org; Sun, 25 Jun 2017 05:15:01 -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 09:15:01 +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.149838207824064 (code B ref 27230); Sun, 25 Jun 2017 09:15:01 +0000 Original-Received: (at 27230) by debbugs.gnu.org; 25 Jun 2017 09:14:38 +0000 Original-Received: from localhost ([127.0.0.1]:36290 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dP3cs-0006G3-0l for submit@debbugs.gnu.org; Sun, 25 Jun 2017 05:14:38 -0400 Original-Received: from sinyavsky.aurox.ch ([37.35.109.145]:49552) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dP3cp-0006Fp-I6 for 27230@debbugs.gnu.org; Sun, 25 Jun 2017 05:14:36 -0400 Original-Received: from sinyavsky.aurox.ch (sinyavsky.aurox.ch [127.0.0.1]) by sinyavsky.aurox.ch (Postfix) with ESMTP id 855CA22483 for <27230@debbugs.gnu.org>; Sun, 25 Jun 2017 09:09:32 +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=1498381769; x=1499245770; bh=Eh0GqXcoMwAQvHHMCnLgTNzI LiKOp7CQUMLM5bSdgSA=; b=TacTF30OLgU8KPKpAC4klgCqalfhrWL4+md/PkuP DLxcfuSSJ52wzKMRjYbJwTuJOpk9GFdBJdPvAWG4JH6gnhTdtuI07yET+e1qwNZ0 ymdZB85Bex0C70RXJTHPkczsKQqYX0EAVUt3oDRDtdX0fkIHgVwkwJ7W2mQNGjd6 xac= 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 RTmQBbVRnq3B for <27230@debbugs.gnu.org>; Sun, 25 Jun 2017 09:09:29 +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 60C8B22443; Sun, 25 Jun 2017 09:09:29 +0000 (UTC) In-Reply-To: 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:133863 Archived-At: This is a multi-part message in MIME format. --------------35029ED80AD546807560BEB5 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit 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. --------------35029ED80AD546807560BEB5 Content-Type: text/x-patch; name="0001-ElDoc-add-docstrings-and-minor-refactoring.patch" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="0001-ElDoc-add-docstrings-and-minor-refactoring.patch" >From 744b20db5524b32302e9cd90cb71dcaec580430e 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 | 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)))) (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)))) @@ -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 --------------35029ED80AD546807560BEB5--