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: [PATCH] RFC: eldoc-documentation-functions hook Date: Sun, 12 Jun 2016 02:12:29 -0400 Message-ID: <20160612061229.GA6463@holos.localdomain> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: ger.gmane.org 1465711979 19558 80.91.229.3 (12 Jun 2016 06:12:59 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 12 Jun 2016 06:12:59 +0000 (UTC) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Jun 12 08:12:53 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 1bBydf-0004yw-PQ for ged-emacs-devel@m.gmane.org; Sun, 12 Jun 2016 08:12:52 +0200 Original-Received: from localhost ([::1]:49874 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bBydb-0004Cg-M5 for ged-emacs-devel@m.gmane.org; Sun, 12 Jun 2016 02:12:47 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:44751) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bBydT-0004CZ-0I for emacs-devel@gnu.org; Sun, 12 Jun 2016 02:12:40 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bBydM-0006Wk-L8 for emacs-devel@gnu.org; Sun, 12 Jun 2016 02:12:37 -0400 Original-Received: from mail-qg0-x232.google.com ([2607:f8b0:400d:c04::232]:33957) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bBydM-0006Wb-FJ for emacs-devel@gnu.org; Sun, 12 Jun 2016 02:12:32 -0400 Original-Received: by mail-qg0-x232.google.com with SMTP id p34so54520634qgp.1 for ; Sat, 11 Jun 2016 23:12:31 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=udel-edu.20150623.gappssmtp.com; s=20150623; h=date:from:to:subject:message-id:mime-version:content-disposition :user-agent; bh=G4J9cg6WLSvSBlW0gqh/DfRdyrnMpoWjEQgDJD500T0=; b=1wMj+Bs723RnhruNVvBLwGIQsPm+EjAr508AUoyWunQgcIqSchSrXva133jr009BYt UIe1gY+QW/ymJsTG2kkEC282xuw4je0azCKOq8+kAzhv0PB5mLDZFGObeXMXuEg6EP2F cd5CKcPeUYixi53+RPNoRIGrGu/J7qna0yLrBLtVlBHem6QVzvFcXDjF5WylpLugIOO8 yv77DFu0VwLRCgn2myqkye+QQ/pXg61pXXOTC1Jh1tQYsbqKWfhkgc2zirKxZYYdDiFN jlw20WE0Gbz31Y9a8BGEz1bbhrCnU3W9T1BNxcm1HCxQ/XyIWCd2V+wwAPn9PH2D/yGq 9i9g== 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:subject:message-id:mime-version :content-disposition:user-agent; bh=G4J9cg6WLSvSBlW0gqh/DfRdyrnMpoWjEQgDJD500T0=; b=CB2aGbk2W2Cw/nnduPnd8QBASDTbmpcsMqa3Ex7rMsnr0B6EiYlDQ7Z+jMcOnuzQyh XNNggJGkY1OwwKdKuCql/PgBRxJr0hKqvTsD0BGAS6DdGlNpq9TRKYFpthPDv0tPmRMi qfV0w8mgTVqHdMFbaaEdS/9gMZlMOEaGh0dUwk1vv2CM6mZrywrsgAZPLbbs/WMc5V3P ZXLh2KfiG1PruAhEPrX7GdGwhZhSc3SUP/+DvBcDJYXuc6WEJBLM960DCWzHof9+ZjNQ NYL1vnr7gwivOG/tz4S6Kb50VaYAbiRcbz4/NU2dXA6k/e6ZeI4wqLcOCJPOV9nk1jr0 INtA== X-Gm-Message-State: ALyK8tLnH/xsZYF669PYTORw6Jm/2Onsrl3ZmlLkvh8bj8xwHGTRP60+UehFm84dfS80wnA5 X-Received: by 10.140.41.83 with SMTP id y77mr8493692qgy.100.1465711950817; Sat, 11 Jun 2016 23:12:30 -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 v6sm5269977qhc.34.2016.06.11.23.12.29 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Sat, 11 Jun 2016 23:12:30 -0700 (PDT) Original-Received: by holos.localdomain (Postfix, from userid 1000) id 603CB69683; Sun, 12 Jun 2016 02:12:29 -0400 (EDT) Content-Disposition: inline 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:c04::232 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:204303 Archived-At: 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. Perhaps the main motivation for doing this is that I don't like the unreadable mess I see when looking at the value of eldoc-documentation-function. For example, the value in *scratch* from emacs -Q. This also exists in other places, like lambdas as defcustom values in eshell, but that's another matter. diff --git a/lisp/emacs-lisp/eldoc.el b/lisp/emacs-lisp/eldoc.el index 6c2f869..bfbfd41 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' handles 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' handles it explicitly." :type '(radio (const :tag "Always" t) (const :tag "Never" nil) (const :tag "Yes, but truncate symbol names if it will\ @@ -113,7 +113,7 @@ 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' +Note that this face has no effect unless the `eldoc-documentation-functions' handles it explicitly." :group 'eldoc) @@ -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 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 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,19 @@ 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." + (when eldoc-documentation-functions + (catch :eldoc-supported + (mapc + (lambda (fun) + (when (not (memq fun '(nil ignore))) + (throw :eldoc-supported t))) + eldoc-documentation-functions) + nil))) ;; 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