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 minor mode.
  22 ;;    A call to `eldoc-overlay-enable' turns it on.
  23 ;;    A call to `eldoc-overlay-disable' turns it off
  24 ;;
  25 ;;    {C-x C-h} interactively calls `eldoc-overlay-toggle' and tells
  26 ;;    you the mode's new state.
  27 ;;
  28 ;;  `global-eldoc-overlay-mode' can be used to toggle this for all buffers.
  29 ;;    A call to `global-eldoc-overlay-enable' turns it on.
  30 ;;    A call to `global-eldoc-overlay-disable' turns it off
  31 ;;
  32 ;;    {C-u C-x C-h} interactively calls `global-eldoc-overlay-toggle' and tells
  33 ;;    you the mode's new state.
  34 ;;
  35 ;; By default, the overlay is not used in the minibuffer, eldoc is shown in the modeline
  36 ;; in this case.  Set the option `eldoc-overlay-in-minibuffer-flag' non-nil if you want
  37 ;; to enable overlay use in the minibuffer.
  38 ;;
  39 ;; Finally, see the documentation for `eldoc-overlay-backend' if you want to try
  40 ;; a different overlay display package backend.
  41
  42 ;;; Code:
  43 ;;; ----------------------------------------------------------------------------
  44
  45 (require 'eldoc)
  46
  47 ;; User Options
  48 (defgroup eldoc-overlay nil
  49   "Display Eldoc function signatures using in-buffer text overlays"
  50   :prefix "eldoc-overlay-"
  51   :group 'eldoc)
  52
  53 (defcustom eldoc-overlay-in-minibuffer-flag nil
  54   "Non-nil (default: nil) means enable `eldoc-overlay-mode' in the minibuffer.
  55 When nil and in the minibuffer, if standard `eldoc-mode' is
  56 enabled, it displays function signatures in the modeline."
  57   :type 'boolean
  58   :group 'eldoc-overlay)
  59
  60
  61 ;; Variables
  62 (defvar eldoc-overlay-backend 'quick-peek
  63   "The backend library that displays eldoc overlays.
  64 Two backends are supported: `inline-docs' and `quick-peek'.")
  65
  66 ;; Functions
  67 (defun eldoc-overlay-inline-docs (format-string &rest args)
  68   "Inline-docs backend function to show FORMAT-STRING and ARGS."
  69   (inline-docs format-string args))
  70
  71 (defun eldoc-overlay-quick-peek (format-string &rest args)
  72   "Quick-peek backend function to show FORMAT-STRING and ARGS."
  73   (when format-string
  74     (quick-peek-show
  75      (apply 'format format-string args)
  76      (point)
  77      1)))
  78
  79 (defun eldoc-overlay-display (format-string &rest args)
  80   "Display eldoc for the minibuffer when there or call the function indexed by `eldoc-overlay-backend'."
  81   (unless (company-tooltip-visible-p)
  82     (if (and (minibufferp) (not eldoc-overlay-in-minibuffer-flag))
  83         (apply #'eldoc-minibuffer-message format-string args)
  84       (funcall
  85        (pcase eldoc-overlay-backend
  86                (`inline-docs 'eldoc-overlay-inline-docs)
  87          (`quick-peek 'eldoc-overlay-quick-peek))
  88              (funcall eldoc-documentation-function)))))
  89
  90 ;;;###autoload
  91 (define-minor-mode eldoc-overlay-mode
  92   "Minor mode for displaying eldoc contextual documentation using a text overlay."
  93   :require 'eldoc-overlay-mode
  94   :group 'eldoc-overlay
  95   :init-value nil
  96   :global t
  97   :lighter " ElDocOver"
  98   (if eldoc-overlay-mode
  99       (progn
 100         (eldoc-mode 1)
 101         (setq eldoc-message-function #'eldoc-overlay-display)
 102         (when (eq eldoc-overlay-backend 'quick-peek)
 103           (add-hook 'post-command-hook #'quick-peek-hide)))
 104     (quick-peek-hide)
 105     ;; Remove hook when no buffers have any peek overlays
 106     (unless (delq nil (mapcar (lambda (buf) (buffer-local-value 'quick-peek--overlays buf)) (buffer-list)))
 107       (remove-hook 'post-command-hook #'quick-peek-hide))
 108     (setq eldoc-message-function #'eldoc-minibuffer-message)))
 109
 110 ;;; ----------------------------------------------------------------------------
 111
 112 (provide 'eldoc-overlay)
 113
 114 ;;; eldoc-overlay.el ends here