From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Mark Oteiza Newsgroups: gmane.emacs.bugs Subject: bug#28257: 26.0.50; [PATCH] expose eldoc functions in a hook Date: Sun, 27 Aug 2017 22:10:57 -0400 Message-ID: <87ziakwifi.fsf@holos> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1503886339 27846 195.159.176.226 (28 Aug 2017 02:12:19 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Mon, 28 Aug 2017 02:12:19 +0000 (UTC) To: 28257@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Mon Aug 28 04:12:12 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 1dm9X6-0006fO-24 for geb-bug-gnu-emacs@m.gmane.org; Mon, 28 Aug 2017 04:12:08 +0200 Original-Received: from localhost ([::1]:36561 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dm9XC-0005ex-In for geb-bug-gnu-emacs@m.gmane.org; Sun, 27 Aug 2017 22:12:14 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:44860) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dm9X3-0005ei-GN for bug-gnu-emacs@gnu.org; Sun, 27 Aug 2017 22:12:07 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dm9X0-0000Ds-8g for bug-gnu-emacs@gnu.org; Sun, 27 Aug 2017 22:12:05 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:49795) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1dm9X0-0000Dl-3H for bug-gnu-emacs@gnu.org; Sun, 27 Aug 2017 22:12:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1dm9Wz-0001tG-Ug for bug-gnu-emacs@gnu.org; Sun, 27 Aug 2017 22:12:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Mark Oteiza Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 28 Aug 2017 02:12:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 28257 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.15038862757184 (code B ref -1); Mon, 28 Aug 2017 02:12:01 +0000 Original-Received: (at submit) by debbugs.gnu.org; 28 Aug 2017 02:11:15 +0000 Original-Received: from localhost ([127.0.0.1]:58466 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dm9WF-0001rn-18 for submit@debbugs.gnu.org; Sun, 27 Aug 2017 22:11:15 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:53741) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dm9WC-0001rY-VE for submit@debbugs.gnu.org; Sun, 27 Aug 2017 22:11:13 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dm9W6-0008KC-7u for submit@debbugs.gnu.org; Sun, 27 Aug 2017 22:11:07 -0400 Original-Received: from lists.gnu.org ([2001:4830:134:3::11]:51711) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1dm9W6-0008K6-5R for submit@debbugs.gnu.org; Sun, 27 Aug 2017 22:11:06 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:44691) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dm9W4-0005Em-1Y for bug-gnu-emacs@gnu.org; Sun, 27 Aug 2017 22:11:05 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dm9W0-0008Ht-Q0 for bug-gnu-emacs@gnu.org; Sun, 27 Aug 2017 22:11:03 -0400 Original-Received: from mail-qt0-x22e.google.com ([2607:f8b0:400d:c0d::22e]:35423) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1dm9W0-0008Hg-Hc for bug-gnu-emacs@gnu.org; Sun, 27 Aug 2017 22:11:00 -0400 Original-Received: by mail-qt0-x22e.google.com with SMTP id x36so19474185qtx.2 for ; Sun, 27 Aug 2017 19:11:00 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=udel-edu.20150623.gappssmtp.com; s=20150623; h=from:to:subject:date:message-id:mime-version :content-transfer-encoding; bh=ZA/E9DH83sotjzdc02L5CF25MvWi+A5YLY13YIYV8z4=; b=Qp29h68PO9RDFC1k6tcqq3hKPsIvL/dRZU5kfGl8yKBotL8V9qF2xd5lTepJt/YC+O b9tauFygvsmbN7Fi4B9noxOCFY/gluwhq6+J2VyJ+PIeRjZQ0J41I71+A4/eupEOOhYq 8JbP1sBrIcxKnwac8TjyfaPNcs4BtY+opsshQCleZmyzqy4HE7cr4jaezGX2on+tTk2s Mn+OyoIx/iuv1j7LCXR96ITjV5DCuypVtxfTubjqmXc7UuQ54txWbVcVUX2KZZH76TEL tVWBcpzM7M83WMMFZ70d73xXHWXTDYci835NlkgdqWkAEWeRmElDY303dAaw+k9Mc/CS n1VA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:subject:date:message-id:mime-version :content-transfer-encoding; bh=ZA/E9DH83sotjzdc02L5CF25MvWi+A5YLY13YIYV8z4=; b=hxgv75ITOfLZAFv54GOV9RddfZIzXf1DIDenP/+e6opraejzndiBudCy7l7ZGZ8H1m 2rmx2JeSsjrnDIzEponMipjZnKtKi8DxXm5DC25q+MzOhm7hX2jDHgLJlV4iLKzwKm7C umcc0MG+dY/5WikCUReNkoPW+Lli1opEsnC7STH58AdyIKfyrDFXyJDcex6sW7BJoKl0 FiL1h7VwX7e82OcfShVwVZLOBDFQfI2wA+glEX4s15aRo4SmCqkT/iyk6sPm8Dhq6IXb xzeTRpUzKuY/j03IBzMgn1qAfOoV/iq51Bxb+2ioiY6UAco9efNqTxAZERsosb+mUqVw VZFQ== X-Gm-Message-State: AHYfb5jW+Nqwvl7ruqrnpNt+Uq7Mk1RY2O2pqmB8tg7K4ZGkLNCekUKk rcRI2hrbjGAVzaaPT/3Rmw== X-Received: by 10.200.48.71 with SMTP id g7mr732699qte.225.1503886259526; Sun, 27 Aug 2017 19:10:59 -0700 (PDT) Original-Received: from holos.localdomain (pool-173-64-88-95.bltmmd.fios.verizon.net. [173.64.88.95]) by smtp.gmail.com with ESMTPSA id m59sm7908593qte.15.2017.08.27.19.10.58 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Sun, 27 Aug 2017 19:10:58 -0700 (PDT) Original-Received: by holos.localdomain (Postfix, from userid 1000) id D112A6B4DD; Sun, 27 Aug 2017 22:10:57 -0400 (EDT) X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x 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:136285 Archived-At: Hi, This makes it possible to use the results from multiple eldoc functions at once, through the addition of an abnormal hook. I'm not aware of a good way to access the default value (or other local values) of eldoc-documentation-function when shadowed by a :before-until advice returning non-nil. Perhaps eldoc-documentation-function should remain a defvar, not sure. diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi index 27ac0eb640..ea7f2f3d26 100644 --- a/doc/emacs/programs.texi +++ b/doc/emacs/programs.texi @@ -1279,9 +1279,27 @@ Lisp Doc for a function, it shows the argument list, and for a variable it shows the first line of the variable's documentation string. To toggle Eldoc mode, type @kbd{M-x eldoc-mode}. There's also a Global -Eldoc mode, which is turned on by default, and affects buffers, such -as @samp{*scratch*}, whose major mode is Emacs Lisp or Lisp -Interaction (@w{@kbd{M-x global-eldoc-mode}} to turn it off globally). +Eldoc mode, which is turned on by default, and affects buffers whose +major mode sets the variables described below. Use @w{@kbd{M-x +global-eldoc-mode}} to turn it off globally. + +@vindex eldoc-documentation-function +@vindex eldoc-documentation-functions + These variables can be used to configure ElDoc mode: + +@table @code +@item eldoc-documentation-function +This variable holds the function which is used to retrieve +documentation for the item at point from the functions in the hook +@code{eldoc-documentation-functions}. By default, +@code{eldoc-documentation-function} returns the first documentation +string produced by the @code{eldoc-documentation-functions} hook. + +@item eldoc-documentation-functions +This abnormal hook holds documentation functions. It acts as a +collection of backends for ElDoc. This is what modes should use to +register their documentation functions with ElDoc. +@end table =20 @node Hideshow @section Hideshow minor mode diff --git a/etc/NEWS b/etc/NEWS index 3f38153048..b2dc06b137 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -791,6 +791,15 @@ breakpoint (e.g. with "f" and "o") by customizing the = new option This allows to enlarge the maximum recursion depth when instrumenting code. =20 +** ElDoc + +*** New hook 'eldoc-documentation-functions' to be used for registering +doc string functions. This makes the results of all doc string +functions accessible to the user through the existing single function hook +'eldoc-documentation-function'. + +*** 'eldoc-documentation-function' is now a custom variable. + ** Eshell =20 *** 'eshell-input-filter's value is now a named function diff --git a/lisp/emacs-lisp/eldoc.el b/lisp/emacs-lisp/eldoc.el index bca40ab87d..7d0ff0f359 100644 --- a/lisp/emacs-lisp/eldoc.el +++ b/lisp/emacs-lisp/eldoc.el @@ -41,9 +41,9 @@ ;; (add-hook 'ielm-mode-hook 'eldoc-mode) ;; (add-hook 'eval-expression-minibuffer-setup-hook 'eldoc-mode) =20 -;; Major modes for other languages may use ElDoc by defining an -;; appropriate function as the buffer-local value of -;; `eldoc-documentation-function'. +;; Major modes for other languages may use ElDoc by adding an +;; appropriate function to the buffer-local value of +;; `eldoc-documentation-functions'. =20 ;;; Code: =20 @@ -222,7 +222,11 @@ turn-on-eldoc-mode =20 (defun eldoc--supported-p () "Non-nil if an ElDoc function is set for this buffer." - (not (memq eldoc-documentation-function '(nil ignore)))) + (let ((hook 'eldoc-documentation-functions)) + (and eldoc-documentation-function + (or (and (local-variable-p hook) + (buffer-local-value hook (current-buffer))) + (default-value hook))))) =20 (defun eldoc-schedule-timer () @@ -341,7 +345,47 @@ eldoc-display-message-no-interference-p =20 ;;;###autoload -(defvar eldoc-documentation-function #'ignore +(defvar eldoc-documentation-functions nil + "Hook for functions to call to return doc string. +Each function should accept no arguments and return a one-line +string for displaying doc about a function etc. appropriate to +the context around point. It should return nil if there's no doc +appropriate for the context. Typically doc is returned if point +is on a function-like name or in its arg list. + +Major modes should modify this hook locally, for example: + (add-hook \\=3D'eldoc-documentation-functions #\\=3D'foo-mode-eldoc nil = t) +so that the global value (i.e. the default value of the hook) is +taken into account if the major mode specific function does not +return any documentation.") + +(defun eldoc-documentation-default () + "Show doc string for item at point. +Default value for `eldoc-documentation-function'." + (let ((res (run-hook-with-args-until-success 'eldoc-documentation-functi= ons))) + (when res + (if eldoc-echo-area-use-multiline-p res + (truncate-string-to-width + res (1- (window-width (minibuffer-window)))))))) + +(defun eldoc-documentation-compose () + "Show multiple doc string results at once. +Meant as a value for `eldoc-documentation-function'." + (let (res) + (run-hook-wrapped + 'eldoc-documentation-functions + (lambda (f) + (let ((str (funcall f))) + (when str (push str res)) + nil))) + (when res + (setq res (mapconcat #'identity (nreverse res) ", ")) + (if eldoc-echo-area-use-multiline-p res + (truncate-string-to-width + res (1- (window-width (minibuffer-window)))))))) + +;;;###autoload +(defcustom eldoc-documentation-function #'eldoc-documentation-default "Function to call to return doc string. The function of no args should return a one-line string for displaying doc about a function etc. appropriate to the context around point. @@ -352,14 +396,12 @@ eldoc-documentation-function The result is used as is, so the function must explicitly handle the variables `eldoc-argument-case' and `eldoc-echo-area-use-multiline-p', and the face `eldoc-highlight-function-argument', if they are to have any -effect. - -Major modes should modify this variable using `add-function', for example: - (add-function :before-until (local \\=3D'eldoc-documentation-function) - #\\=3D'foo-mode-eldoc-function) -so that the global documentation function (i.e. the default value of the -variable) is taken into account if the major mode specific function does n= ot -return any documentation.") +effect." + :link '(info-link "(emacs) Lisp Doc") + :type '(radio (function-item eldoc-documentation-default) + (function-item eldoc-documentation-compose) + (function :tag "Other function")) + :group 'eldoc) =20 (defun eldoc-print-current-symbol-info () "Print the text produced by `eldoc-documentation-function'." @@ -371,7 +413,8 @@ eldoc-print-current-symbol-info (when eldoc-last-message (eldoc-message nil) nil)) - (eldoc-message (funcall eldoc-documentation-function))))) + (let ((fun eldoc-documentation-function)) + (when fun (eldoc-message (funcall fun))))))) =20 ;; If the entire line cannot fit in the echo area, the symbol name may be ;; truncated or eliminated entirely from the output to make room for the diff --git a/lisp/hexl.el b/lisp/hexl.el index 0a598b22f6..e1c5386c1a 100644 --- a/lisp/hexl.el +++ b/lisp/hexl.el @@ -395,8 +395,8 @@ hexl-mode (add-hook 'change-major-mode-hook 'hexl-maybe-dehexlify-buffer nil t) =20 ;; Set a callback function for eldoc. - (add-function :before-until (local 'eldoc-documentation-function) - #'hexl-print-current-point-info) + (add-hook 'eldoc-documentation-functions + #'hexl-print-current-point-info nil t) (eldoc-add-command-completions "hexl-") (eldoc-remove-command "hexl-save-buffer" "hexl-current-address") @@ -506,6 +506,8 @@ hexl-mode-exit =20 (remove-hook 'change-major-mode-hook 'hexl-maybe-dehexlify-buffer t) (remove-hook 'post-command-hook 'hexl-follow-ascii-find t) + (remove-hook 'eldoc-documentation-functions + #'hexl-print-current-point-info t) (setq hexl-ascii-overlay nil) =20 (let ((mms ())) diff --git a/lisp/ielm.el b/lisp/ielm.el index 42b065fe62..3e8b8198f5 100644 --- a/lisp/ielm.el +++ b/lisp/ielm.el @@ -541,8 +541,8 @@ inferior-emacs-lisp-mode (set (make-local-variable 'completion-at-point-functions) '(comint-replace-by-expanded-history ielm-complete-filename elisp-completion-at-point)) - (add-function :before-until (local 'eldoc-documentation-function) - #'elisp-eldoc-documentation-function) + (add-hook 'eldoc-documentation-functions + #'elisp-eldoc-documentation-function nil t) (set (make-local-variable 'ielm-prompt-internal) ielm-prompt) (set (make-local-variable 'comint-prompt-read-only) ielm-prompt-read-onl= y) (setq comint-get-old-input 'ielm-get-old-input) diff --git a/lisp/progmodes/cfengine.el b/lisp/progmodes/cfengine.el index 5bc7b66063..c775a18220 100644 --- a/lisp/progmodes/cfengine.el +++ b/lisp/progmodes/cfengine.el @@ -1390,12 +1390,15 @@ cfengine3-mode (when buffer-file-name (shell-quote-argument buffer-file-name))))) =20 - ;; For emacs < 25.1 where `eldoc-documentation-function' defaults to - ;; nil. - (or eldoc-documentation-function - (setq-local eldoc-documentation-function #'ignore)) - (add-function :before-until (local 'eldoc-documentation-function) - #'cfengine3-documentation-function) + (if (> emacs-major-version 25) + (add-hook 'eldoc-documentation-functions + #'cfengine3-documentation-function nil t) + ;; For emacs < 25.1 where `eldoc-documentation-function' defaults + ;; to nil. + (or eldoc-documentation-function + (setq-local eldoc-documentation-function #'ignore)) + (add-function :before-until (local 'eldoc-documentation-function) + #'cfengine3-documentation-function)) =20 (add-hook 'completion-at-point-functions #'cfengine3-completion-function nil t) diff --git a/lisp/progmodes/elisp-mode.el b/lisp/progmodes/elisp-mode.el index b3f452ca5b..07210381f3 100644 --- a/lisp/progmodes/elisp-mode.el +++ b/lisp/progmodes/elisp-mode.el @@ -235,8 +235,8 @@ emacs-lisp-mode (append '((?\` . ?\') (?=E2=80=98 . ?=E2=80=99)) electric-pa= ir-text-pairs)) (setq-local electric-quote-string t) (setq imenu-case-fold-search nil) - (add-function :before-until (local 'eldoc-documentation-function) - #'elisp-eldoc-documentation-function) + (add-hook 'eldoc-documentation-functions + #'elisp-eldoc-documentation-function nil t) (add-hook 'xref-backend-functions #'elisp--xref-backend nil t) (setq-local project-vc-external-roots-function #'elisp-load-path-roots) (add-hook 'completion-at-point-functions diff --git a/lisp/progmodes/octave.el b/lisp/progmodes/octave.el index ac9ba630c4..5843361dbd 100644 --- a/lisp/progmodes/octave.el +++ b/lisp/progmodes/octave.el @@ -596,8 +596,7 @@ octave-mode (add-hook 'before-save-hook 'octave-sync-function-file-names nil t) (setq-local beginning-of-defun-function 'octave-beginning-of-defun) (and octave-font-lock-texinfo-comment (octave-font-lock-texinfo-comment)) - (add-function :before-until (local 'eldoc-documentation-function) - 'octave-eldoc-function) + (add-hook 'eldoc-documentation-functions 'octave-eldoc-function nil t) =20 (easy-menu-add octave-mode-menu)) =20 diff --git a/lisp/progmodes/python.el b/lisp/progmodes/python.el index 6f169123b9..8b4cfaa77a 100644 --- a/lisp/progmodes/python.el +++ b/lisp/progmodes/python.el @@ -5198,8 +5198,10 @@ python-mode ;; Emacs<25 (set (make-local-variable 'eldoc-documentation-function) #'python-eldoc-function) - (add-function :before-until (local 'eldoc-documentation-function) - #'python-eldoc-function)) + (if (< emacs-major-version 26) + (add-function :before-until (local 'eldoc-documentation-function) + #'python-eldoc-function) + (add-hook 'eldoc-documentation-functions #'python-eldoc-function nil= t))) =20 (add-to-list 'hs-special-modes-alist diff --git a/lisp/simple.el b/lisp/simple.el index 58f8372192..f56a505523 100644 --- a/lisp/simple.el +++ b/lisp/simple.el @@ -1490,8 +1490,8 @@ read--expression (minibuffer-with-setup-hook (lambda () ;; FIXME: call emacs-lisp-mode? - (add-function :before-until (local 'eldoc-documentation-function) - #'elisp-eldoc-documentation-function) + (add-hook 'eldoc-documentation-functions + #'elisp-eldoc-documentation-function nil t) (eldoc-mode 1) (add-hook 'completion-at-point-functions #'elisp-completion-at-point nil t)