unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
* [PATCH] RFC: eldoc-documentation-functions hook
@ 2016-06-12  6:12 Mark Oteiza
  2016-06-12  7:09 ` Eli Zaretskii
  2016-06-12 13:23 ` [PATCH] " Noam Postavsky
  0 siblings, 2 replies; 32+ messages in thread
From: Mark Oteiza @ 2016-06-12  6:12 UTC (permalink / raw)
  To: emacs-devel

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
 
 \f
 ;;;###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



^ permalink raw reply related	[flat|nested] 32+ messages in thread

end of thread, other threads:[~2016-07-20 23:03 UTC | newest]

Thread overview: 32+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2016-06-12  6:12 [PATCH] RFC: eldoc-documentation-functions hook Mark Oteiza
2016-06-12  7:09 ` Eli Zaretskii
2016-06-12  7:46   ` Leo Liu
2016-06-12  8:33     ` Eli Zaretskii
2016-06-12 18:24   ` Mark Oteiza
2016-06-13 21:17     ` Mark Oteiza
2016-06-17 21:08       ` [PATCH v3] " Mark Oteiza
2016-07-07  3:30         ` Mark Oteiza
2016-07-07  4:12           ` Leo Liu
2016-07-07 10:02             ` Kaushal Modi
2016-07-17 15:17               ` Noam Postavsky
2016-07-17 17:48                 ` Mark Oteiza
2016-07-17 23:47                   ` Dmitry Gutov
2016-07-18  0:09                     ` Leo Liu
2016-07-17 18:28             ` Stefan Monnier
2016-07-17 18:52               ` Stefan Monnier
2016-07-18 21:27                 ` Mark Oteiza
2016-07-19  2:47                   ` Stefan Monnier
2016-07-19 23:20                     ` Mark Oteiza
2016-07-20  1:50                       ` Clément Pit--Claudel
2016-07-20  4:50                       ` John Wiegley
2016-07-20 23:03                         ` Mark Oteiza
2016-07-07 14:55           ` Clément Pit--Claudel
2016-06-12 13:23 ` [PATCH] " Noam Postavsky
2016-06-12 18:52   ` Mark Oteiza
2016-06-12 18:57     ` Dmitry Gutov
2016-06-12 19:44       ` Mark Oteiza
2016-06-12 19:50         ` Dmitry Gutov
2016-06-13 20:36         ` Richard Stallman
2016-06-19  2:45           ` Dmitry Gutov
2016-06-20 23:00             ` Richard Stallman
2016-06-13  4:37     ` Leo Liu

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).