From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Mark Oteiza Newsgroups: gmane.emacs.devel Subject: Re: [PATCH v3] RFC: eldoc-documentation-functions hook Date: Fri, 17 Jun 2016 17:08:49 -0400 Message-ID: <20160617210849.GA3775@holos.localdomain> References: <20160612061229.GA6463@holos.localdomain> <838tyahoim.fsf@gnu.org> <20160612182453.GA12034@holos.localdomain> <20160613211735.GA5969@holos.localdomain> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: ger.gmane.org 1466197756 29707 80.91.229.3 (17 Jun 2016 21:09:16 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 17 Jun 2016 21:09:16 +0000 (UTC) Cc: emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Jun 17 23:09:09 2016 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1bE10l-00006C-9b for ged-emacs-devel@m.gmane.org; Fri, 17 Jun 2016 23:09:07 +0200 Original-Received: from localhost ([::1]:60328 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bE10k-0007gn-3u for ged-emacs-devel@m.gmane.org; Fri, 17 Jun 2016 17:09:06 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:38057) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bE10d-0007gF-If for emacs-devel@gnu.org; Fri, 17 Jun 2016 17:09:01 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bE10X-0006W8-U2 for emacs-devel@gnu.org; Fri, 17 Jun 2016 17:08:58 -0400 Original-Received: from mail-qk0-x234.google.com ([2607:f8b0:400d:c09::234]:33703) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bE10X-0006Tq-OW for emacs-devel@gnu.org; Fri, 17 Jun 2016 17:08:53 -0400 Original-Received: by mail-qk0-x234.google.com with SMTP id a186so98293624qkf.0 for ; Fri, 17 Jun 2016 14:08:52 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=udel-edu.20150623.gappssmtp.com; s=20150623; h=date:from:to:cc:subject:message-id:references:mime-version :content-disposition:in-reply-to:user-agent; bh=mYrV3+VIrTQ9TOR2lzxVtqJTT009onJ/u68a39cntfE=; b=E4ZQgAndvFbDA+VwRyS9TeeLY9Iqrzv4MdePBXlRwIs0j/oooyk/uahULhrqIU/OAy 6g9CWWj24Fjnzwppepc06bTujx/g1t+2I8/MD/jS/sabl9Ru+WmDfwaIU8pcrnCY8F76 T+v0BTUjArmtH0lmduM7Ou10E5rYkuyDG7KOmsxWvFfXN2CY1CtZ8kXtoeZkHbRnbZAW cydbnbGgMzwMhk0zs4EV4liO230HilNhdPAvF9ftfls+luJ0Q/oP8VFQFsZnKslJKO0Y kSHdqBvuAMCjZ/aoF6kjxxv5GYNwHTkhjKp6MAWjC2WszZNezHJfOSfBlP3fadXC6Pde IuWg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:date:from:to:cc:subject:message-id:references :mime-version:content-disposition:in-reply-to:user-agent; bh=mYrV3+VIrTQ9TOR2lzxVtqJTT009onJ/u68a39cntfE=; b=DiLCmyn6w/DpI+AUE1eE9cdc7gcGxckTOf6JncGDDgWGL4hE5KDsgjSY0B/mAxts9m bjfo1FtOhaX9bxwlTalxaksAej61mfai5uMs0v7aL9OhDkbj3zWtSL6hkDuRHUcTZXSb M3U7pEn9aRae8dZ0h9GOeCESFyOKvgtn4hHmmr3Xo9Tl864vi98/Ngif3e+BE3Hzra3A 5qYOcfUlih6tT4T/beLSIOwoo1bfq6meORVyqA9malIroXQWBHs6yfCcNHrP4NL6siw2 FIZN7sMgqQMw9nG0Ro8JeS4yPKYkUv/DiejDotBpbfbYtpDTnsKSyVQcPdm/QcBoFmrM fiEA== X-Gm-Message-State: ALyK8tJ9YhytV3r5T5msamLMHxAqv4MPwq74rsevioCz90CkSwresTminktaYp9DADrZWz28 X-Received: by 10.55.212.133 with SMTP id s5mr4715109qks.85.1466197731582; Fri, 17 Jun 2016 14:08:51 -0700 (PDT) Original-Received: from holos.localdomain (ip68-100-200-121.dc.dc.cox.net. [68.100.200.121]) by smtp.gmail.com with ESMTPSA id r47sm11012476qtc.36.2016.06.17.14.08.50 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 17 Jun 2016 14:08:50 -0700 (PDT) Original-Received: by holos.localdomain (Postfix, from userid 1000) id 03D0469683; Fri, 17 Jun 2016 17:08:49 -0400 (EDT) Content-Disposition: inline In-Reply-To: <20160613211735.GA5969@holos.localdomain> User-Agent: Mutt/1.6.1+26 (8e342d73159b) (2016-04-27) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2607:f8b0:400d:c09::234 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:204455 Archived-At: --- On 13/06/16 at 05:17pm, Mark Oteiza wrote: > On 12/06/16 at 02:24pm, Mark Oteiza wrote: > > On 12/06/16 at 10:09am, Eli Zaretskii wrote: > > > > Date: Sun, 12 Jun 2016 02:12:29 -0400 > > > > From: Mark Oteiza > > > > > > > > This is a draft patch changing eldoc-documentation-function into a hook > > > > variable, so instead of using add-function, one can instead use add-hook > > > > to control the behavior of eldoc. It is backwards compatible. > > > > > > Thanks. Please be sure to update the ELisp manual accordingly. > > > > changed the default value back to nil, since this isn't being > > unconditionally funcall'd anymore. > > Ah, this was a mistake wrt backwards compatibility. The default can be > changed sometime in the future, I suppose. > > Also had to fix eldoc-supported-p... > > > In the manual, it appears that the -functions suffix is to be used for > > abnormal hooks; however this is a normal hook, so it would seem the name > > should use the -hook suffix. > > ... but I'll wait for some judgement on this before sending another > patch. Nevermind, I missed the part of the manual that says -functions is used when a hooks result is used. Here is the patch that I have been using. No problems encountered. diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index 7b76e6a..b5d07da 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -417,7 +417,7 @@ Major Mode Conventions @item The mode can specify a local value for -@code{eldoc-documentation-function} to tell ElDoc mode how to handle +@code{eldoc-documentation-functions} to tell ElDoc mode how to handle this mode. @item diff --git a/etc/NEWS b/etc/NEWS index e2c99a1..92bf8e4 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -212,6 +212,11 @@ viewing HTML files and the like. breakpoint (e.g. with "f" and "o") by customizing the new option 'edebug-sit-on-break'. +** ElDoc + ++++ +*** 'eldoc-documentation-functions' replaces 'eldoc-documentation-function'. + ** eww +++ diff --git a/lisp/emacs-lisp/eldoc.el b/lisp/emacs-lisp/eldoc.el index 6c2f869..67d0a9e 100644 --- a/lisp/emacs-lisp/eldoc.el +++ b/lisp/emacs-lisp/eldoc.el @@ -43,7 +43,7 @@ ;; Major modes for other languages may use ElDoc by defining an ;; appropriate function as the buffer-local value of -;; `eldoc-documentation-function'. +;; `eldoc-documentation-functions'. ;;; Code: @@ -80,7 +80,7 @@ eldoc-argument-case returns another string is acceptable. Note that this variable has no effect, unless -`eldoc-documentation-function' handles it explicitly." +`eldoc-documentation-functions' handle it explicitly." :type '(radio (function-item upcase) (function-item downcase) function) @@ -103,7 +103,7 @@ eldoc-echo-area-use-multiline-p truncated to make more of the arglist or documentation string visible. Note that this variable has no effect, unless -`eldoc-documentation-function' handles it explicitly." +`eldoc-documentation-functions' handle it explicitly." :type '(radio (const :tag "Always" t) (const :tag "Never" nil) (const :tag "Yes, but truncate symbol names if it will\ @@ -113,8 +113,8 @@ eldoc-echo-area-use-multiline-p (defface eldoc-highlight-function-argument '((t (:inherit bold))) "Face used for the argument at point in a function's argument list. -Note that this face has no effect unless the `eldoc-documentation-function' -handles it explicitly." +Note that this face has no effect unless the `eldoc-documentation-functions' +handle it explicitly." :group 'eldoc) ;;; No user options below here. @@ -186,7 +186,7 @@ eldoc-mode :group 'eldoc :lighter eldoc-minor-mode-string (setq eldoc-last-message nil) (cond - ((memq eldoc-documentation-function '(nil ignore)) + ((not (eldoc-supported-p)) (message "There is no ElDoc support in this buffer") (setq eldoc-mode nil)) (eldoc-mode @@ -211,7 +211,7 @@ global-eldoc-mode If Global Eldoc mode is on, `eldoc-mode' will be enabled in all buffers where it's applicable. These are buffers that have modes -that have enabled eldoc support. See `eldoc-documentation-function'." +that have enabled eldoc support. See `eldoc-documentation-functions'." :group 'eldoc :global t :initialize 'custom-initialize-delay @@ -236,9 +236,7 @@ eldoc-schedule-timer eldoc-idle-delay nil (lambda () (when (or eldoc-mode - (and global-eldoc-mode - (not (memq eldoc-documentation-function - '(nil ignore))))) + (and global-eldoc-mode (eldoc-supported-p))) (eldoc-print-current-symbol-info)))))) ;; If user has changed the idle delay, update the timer. @@ -334,26 +332,29 @@ eldoc-display-message-no-interference-p ;;;###autoload -(defvar eldoc-documentation-function #'ignore - "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. -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. +(defvar eldoc-documentation-functions #'ignore + "Hook to run to obtain doc string. +Each element of this variable should be a function of no args +that returns a one-line string for displaying doc about a +function etc. appropriate to the context around point. It should +return nil if there is no doc appropriate for the context. +Typically, doc is returned if point is on a function-like name or +in its arg list. 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 \\='eldoc-documentation-function) - #\\='foo-mode-eldoc-function) +Major modes should modify this variable using `add-hook', for example: + (add-hook \\='eldoc-documentation-functions #\\='foo-eldoc nil t) 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 not return any documentation.") +(define-obsolete-variable-alias 'eldoc-documentation-function + 'eldoc-documentation-functions "25.2") + (defun eldoc-print-current-symbol-info () ;; This is run from post-command-hook or some idle timer thing, ;; so we need to be careful that errors aren't ignored. @@ -363,7 +364,20 @@ eldoc-print-current-symbol-info (when eldoc-last-message (eldoc-message nil) nil)) - (eldoc-message (funcall eldoc-documentation-function))))) + (eldoc-message + (run-hook-with-args-until-success 'eldoc-documentation-functions))))) + +(defun eldoc-supported-p () + "Return t if `eldoc-documentation-functions' has non-null elements." + (if (listp eldoc-documentation-functions) + (catch :eldoc-supported + (mapc + (lambda (fun) + (when (not (memq fun '(nil ignore))) + (throw :eldoc-supported t))) + eldoc-documentation-functions) + nil) + (not (memq eldoc-documentation-functions '(nil ignore))))) ;; 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