From 6d454a2313987a8a1124a57764b3b6482c45f57c Mon Sep 17 00:00:00 2001
From: bmag <bmagamb@gmail.com>
Date: Fri, 26 Aug 2016 15:37:05 +0300
Subject: [PATCH] auto-completion: manual help tooltip and minor fix

New value `manual` for auto-completion-enable-help-tooltip enables the
user to display help tooltip on-demand. Other values remain the same:
nil for no tooltip at all, t (or any non-nil non-manual value) for
automatic tooltip.

Minor fix: call `company-quickhelp-mode` just once, because it's a
global minor-mode.
---
 layers/+completion/auto-completion/README.org | 23 ++++++++++++++-----
 layers/+completion/auto-completion/config.el  |  4 +++-
 .../+completion/auto-completion/packages.el   |  8 ++++---
 3 files changed, 25 insertions(+), 10 deletions(-)

diff --git a/layers/+completion/auto-completion/README.org b/layers/+completion/auto-completion/README.org
index 5b7b4b9d9..0b46a6324 100644
--- a/layers/+completion/auto-completion/README.org
+++ b/layers/+completion/auto-completion/README.org
@@ -102,7 +102,8 @@ the popup, set the variable =auto-completion-enable-snippets-in-popup= to =t=.
 #+END_SRC
 
 ** Tooltips
-To enable docstring tooltips set =auto-completion-enable-help-tooltip= to =t=
+To enable automatic docstring tooltips set =auto-completion-enable-help-tooltip=
+to =t=.
 
 #+BEGIN_SRC emacs-lisp
 (setq-default dotspacemacs-configuration-layers
@@ -110,6 +111,15 @@ To enable docstring tooltips set =auto-completion-enable-help-tooltip= to =t=
                     auto-completion-enable-help-tooltip t)))
 #+END_SRC
 
+To enable manual non-automatic invocation of docstring tooltips, set it to
+=manual=. The tooltip can be invoked manually by pressing ~M-h~.
+
+#+BEGIN_SRC emacs-lisp
+(setq-default dotspacemacs-configuration-layers
+  '((auto-completion :variables
+                    auto-completion-enable-help-tooltip 'manual)))
+#+END_SRC
+
 ** Sort results by usage
 To enable sorting auto-completion results by their usage frequency set
 =auto-completion-enable-sort-by-usage= to =t=.
@@ -197,11 +207,12 @@ For nicer-looking faces, try adding the following to `custom-set-faces` in your
 * Key Bindings
 ** Company
 
-| Key Binding | Description                                                              |
-|-------------+--------------------------------------------------------------------------|
-| ~C-d~       | open minibuffer with documentation of thing at point in company dropdown |
-| ~C-/~       | show candidates in Helm (for fuzzy searching)                            |
-| ~C-M-/~     | filter the company dropdown menu                                         |
+| Key Binding | Description                                                                                          |
+|-------------+------------------------------------------------------------------------------------------------------|
+| ~C-d~       | open minibuffer with documentation of thing at point in company dropdown                             |
+| ~C-/~       | show candidates in Helm (for fuzzy searching)                                                        |
+| ~C-M-/~     | filter the company dropdown menu                                                                     |
+| ~M-h~       | show current candidate's documentation in a tooltip (requires =auto-completion-enable-help-tooltip=) |
 
 Vim Style:
 
diff --git a/layers/+completion/auto-completion/config.el b/layers/+completion/auto-completion/config.el
index 655829521..6e63c8e7b 100644
--- a/layers/+completion/auto-completion/config.el
+++ b/layers/+completion/auto-completion/config.el
@@ -37,7 +37,9 @@ selection.")
   "If non nil suggestions are sorted by how often they are used.")
 
 (defvar auto-completion-enable-help-tooltip nil
-  "If non nil the docstring appears in a tooltip.")
+  "If non nil the docstring appears in a tooltip.
+If set to `manual', help tooltip appears only when invoked
+manually.")
 
 (defvar company-mode-completion-cancel-keywords
   '("do"
diff --git a/layers/+completion/auto-completion/packages.el b/layers/+completion/auto-completion/packages.el
index 6f1b49f1e..5420240f0 100644
--- a/layers/+completion/auto-completion/packages.el
+++ b/layers/+completion/auto-completion/packages.el
@@ -114,12 +114,14 @@
 
 (defun auto-completion/init-company-quickhelp ()
   (use-package company-quickhelp
-    :defer t
+    :commands company-quickhelp-manual-begin
     :init
     (spacemacs|do-after-display-system-init
-     (add-hook 'company-mode-hook 'company-quickhelp-mode)
      (with-eval-after-load 'company
-       (setq company-frontends (delq 'company-echo-metadata-frontend company-frontends))))))
+       (setq company-frontends (delq 'company-echo-metadata-frontend company-frontends))
+       (define-key company-active-map (kbd "M-h") #'company-quickhelp-manual-begin)
+       (unless (eq auto-completion-enable-help-tooltip 'manual)
+         (company-quickhelp-mode))))))
 
 (defun auto-completion/init-helm-c-yasnippet ()
   (use-package helm-c-yasnippet