eldoc-overlay.el

   1 ;;; eldoc-overlay.el --- Display eldoc with contextual documentation overlay.
   2
   3 ;; Author: stardiviner <numbchild@gmail.com>
   4 ;; Author: Robert Weiner <rsw@gnu.org>
   5 ;; Maintainer: stardiviner <numbchild@gmail.com>
   6 ;; Keywords: documentation, eldoc, overlay
   7 ;; URL: https://github.com/stardiviner/eldoc-overlay
   8 ;; Created:  14th Jan 2017
   9 ;; Modified: 18th Dec 2017
  10 ;; Version: 0.1.1
  11 ;; Package-Requires: ((emacs "24.3") (inline-docs "1.0.1") (quick-peek "1.0"))
  12
  13 ;;; Commentary:
  14 ;;
  15 ;; Eldoc displays the function signature of the closest function call
  16 ;; around point either in the minibuffer or in the modeline.
  17 ;;
  18 ;; This package modifies Eldoc to display this documentation inline
  19 ;; using a buffer text overlay.
  20 ;;
  21 ;;  `eldoc-overlay-mode' is a per-buffer local minor mode.
  22 ;;
  23 ;; By default, the overlay is not used in the minibuffer, eldoc is shown in the modeline
  24 ;; in this case.  Set the option `eldoc-overlay-enable-in-minibuffer' non-nil if you want
  25 ;; to enable overlay use in the minibuffer.
  26 ;;
  27 ;; Finally, see the documentation for `eldoc-overlay-backend' if you want to try
  28 ;; a different overlay display package backend.
  29
  30 ;;; Code:
  31 ;;; ----------------------------------------------------------------------------
  32
  33 (require 'eldoc)
  34
  35 ;; User Options
  36 (defgroup eldoc-overlay nil
  37   "Display Eldoc function signatures using in-buffer text overlays"
  38   :prefix "eldoc-overlay-"
  39   :group 'eldoc)
  40
  41 (defcustom eldoc-overlay-enable-in-minibuffer nil
  42   "Non-nil (default: nil) means enable `eldoc-overlay-mode' in the minibuffer.
  43 When nil and in the minibuffer, if standard `eldoc-mode' is
  44 enabled, it displays function signatures in the modeline."
  45   :type 'boolean
  46   :group 'eldoc-overlay)
  47
  48
  49 ;; Variables
  50 (defvar eldoc-overlay-backend 'quick-peek
  51   "The backend library that displays eldoc overlays.
  52 Two backends are supported: `inline-docs' and `quick-peek'.")
  53
  54 ;; Functions
  55 (defun eldoc-overlay-inline-docs (format-string &rest args)
  56   "Inline-docs backend function to show FORMAT-STRING and ARGS."
  57   (inline-docs format-string args))
  58
  59 (defun eldoc-overlay-quick-peek (format-string &rest args)
  60   "Quick-peek backend function to show FORMAT-STRING and ARGS."
  61   (when format-string
  62     (quick-peek-show
  63      (apply 'format format-string args)
  64      (point)
  65      1)))
  66
  67 (defun eldoc-overlay-display (format-string &rest args)
  68   "Display eldoc for the minibuffer when there or call the function indexed by `eldoc-overlay-backend'."
  69   (unless (or (company-tooltip-visible-p)
  70               (when (company-box--get-frame)
  71                 (frame-visible-p (company-box--get-frame))))
  72     (if (and (minibufferp) (not eldoc-overlay-enable-in-minibuffer))
  73         (apply #'eldoc-minibuffer-message format-string args)
  74       (funcall
  75        (pcase eldoc-overlay-backend
  76                (`inline-docs 'eldoc-overlay-inline-docs)
  77          (`quick-peek 'eldoc-overlay-quick-peek))
  78              (funcall eldoc-documentation-function)))))
  79 (defun eldoc-overlay-enable ()
  80   (unless eldoc-mode
  81     (eldoc-mode 1)) ; make sure `eldoc-mode' enabled.
  82   (setq-local eldoc-message-function #'eldoc-overlay-display)
  83   (when (eq eldoc-overlay-backend 'quick-peek)
  84     (add-hook 'post-command-hook #'quick-peek-hide)))
  85
  86 (defun eldoc-overlay-disable ()
  87   (pcase eldoc-overlay-backend
  88     ('quick-peek
  89      (quick-peek-hide)
  90      ;; Remove hook when no buffers have any peek overlays
  91      (unless (delq nil (mapcar (lambda (buf) (buffer-local-value 'quick-peek--overlays buf)) (buffer-list)))
  92        (remove-hook 'post-command-hook #'quick-peek-hide)))
  93     ('inline-docs
  94      ))
  95   (setq-local eldoc-message-function #'eldoc-minibuffer-message))
  96
  97 ;;;###autoload
  98 (define-minor-mode eldoc-overlay-mode
  99   "Minor mode for displaying eldoc contextual documentation using a text overlay."
 100   :require 'eldoc-overlay-mode
 101   :group 'eldoc-overlay
 102   :init-value nil
 103   :global nil
 104   :lighter " ElDoc/overlay"
 105   (if eldoc-overlay-mode
 106       (eldoc-overlay-enable)
 107     (eldoc-overlay-disable)))
 108
 109 ;;;###autoload
 110 (add-hook 'eldoc-mode-hook #'eldoc-overlay-mode)
 111
 112 ;;; ----------------------------------------------------------------------------
 113
 114 (provide 'eldoc-overlay)
 115
 116 ;;; eldoc-overlay.el ends here