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: Wed, 6 Jul 2016 23:30:19 -0400 Message-ID: <20160707033019.GA22360@holos.localdomain> References: <20160612061229.GA6463@holos.localdomain> <838tyahoim.fsf@gnu.org> <20160612182453.GA12034@holos.localdomain> <20160613211735.GA5969@holos.localdomain> <20160617210849.GA3775@holos.localdomain> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: ger.gmane.org 1467862245 5018 80.91.229.3 (7 Jul 2016 03:30:45 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Thu, 7 Jul 2016 03:30:45 +0000 (UTC) Cc: emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Jul 07 05:30:39 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 1bL01N-000727-1m for ged-emacs-devel@m.gmane.org; Thu, 07 Jul 2016 05:30:37 +0200 Original-Received: from localhost ([::1]:37262 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bL01M-0003j9-3J for ged-emacs-devel@m.gmane.org; Wed, 06 Jul 2016 23:30:36 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:56363) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bL01C-0003bI-Vl for emacs-devel@gnu.org; Wed, 06 Jul 2016 23:30:28 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bL018-0001aK-IJ for emacs-devel@gnu.org; Wed, 06 Jul 2016 23:30:25 -0400 Original-Received: from mail-qt0-x233.google.com ([2607:f8b0:400d:c0d::233]:35457) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bL018-0001aA-BB for emacs-devel@gnu.org; Wed, 06 Jul 2016 23:30:22 -0400 Original-Received: by mail-qt0-x233.google.com with SMTP id f89so2775691qtd.2 for ; Wed, 06 Jul 2016 20:30:21 -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=iEkeYIvzlVm3bRbdg6/P7motY/ZSGgmtTbPRQI+eZgE=; b=HRWUV4GSp78IY7ZhMs+UTwUN3yePQEsqDDLujIvYPnNK7feNNAex4J0jlEOOdZu10T Dwr3IH115FTotkRthkUsw+mN5NAICcUvn1yWcSs00xSzqxhZ0uJUDYHCE2K7Pq7eQqZI CiQtpyA/PpmUNnnkxNC+y3FV+noqan2fPnA0ESJ//Mq1una60Bt5RztK0MnsBylfwr1v FDu6Rzac8R5IWtKGz69jLtABPCeFK/Psv9B7zxoLnQKlYJmpxi1oovWKPDUWALLU+ikr MVv+4fH7898pTQHBcMDl5ABiBxjiDRE1FKjL1YpTXnQY2nEsMtpwooWzy+B5JXiukHy+ eXkw== 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=iEkeYIvzlVm3bRbdg6/P7motY/ZSGgmtTbPRQI+eZgE=; b=S2X7oyPJVpoQlexw39TZYQrzhjq9RWOzi2mBZuABh/xUATzwiprUyGDweSiyaMXUdM ekip3U1WNwMnirTaUAeHqoZeFBlckWceHU5ZmV29yayPEMMT7/C3oU8P1dLOdmEn9n+u ua3S5iqc5XAEzFf6wz+Efbm3pK0wUesOwZkmbl5VSVIVc9HJFzcXje4e7VB8xuzwQViy dAs+mMjm8O2fOzTABW4GO4a48JeHxQIbzkAFoaPOyMVZF/A5gz4GSIOLkY+b5cRdJNyb j0oOg8yz9kcYQxFbVqYr4UD8mnkGfgB1E4hCmkDCFTtG1h+uMHQlFGhZ45hWiJg7YGY+ 8CzQ== X-Gm-Message-State: ALyK8tLgjN9k8v3V1cq5B4ghGF/Y2ltFdpCZkYjpty9FrBtjkCb6u9SkL1t3XBKjdArpzPQ+ X-Received: by 10.200.39.66 with SMTP id h2mr38956726qth.7.1467862221237; Wed, 06 Jul 2016 20:30:21 -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 f126sm3087284qkb.27.2016.07.06.20.30.20 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Wed, 06 Jul 2016 20:30:20 -0700 (PDT) Original-Received: by holos.localdomain (Postfix, from userid 1000) id 9B48C685B5; Wed, 6 Jul 2016 23:30:19 -0400 (EDT) Content-Disposition: inline In-Reply-To: <20160617210849.GA3775@holos.localdomain> User-Agent: Mutt/1.6.1+68 (bf1c73de2b7c) (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:c0d::233 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:205297 Archived-At: On 17/06/16 at 05:08pm, Mark Oteiza wrote: > --- > 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 Applied with some wording changes as 5811404