[elpa] externals/company 3ed68587b3 1/2: company-show-doc-buffer: Add prefix argument toggle-auto-update

[ELPA Syncer]

branch: externals/company
commit 3ed68587b3c48cec8de959ff2e75a282f83bfeb8
Author: Felician Nemeth <nemethf@tmit.bme.hu>
Commit: Felician Nemeth <nemethf@tmit.bme.hu>

    company-show-doc-buffer: Add prefix argument toggle-auto-update
    
    `company-show-doc-buffer` now can accept a prefix argument to toggle a new
    variable `company-auto-update-doc`.  When this variable is non-nil, it 
keeps the
    documentation buffer up-to-date whenever the selection changes (#1331).
---
 NEWS.md          |  4 ++++
 company.el       | 33 +++++++++++++++++++++++++++------
 doc/company.texi |  4 +++-
 3 files changed, 34 insertions(+), 7 deletions(-)

diff --git a/NEWS.md b/NEWS.md
index 550324cea2..0456819cc1 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -2,6 +2,10 @@
 
 ## Next
 
+* `company-show-doc-buffer` now can accept a prefix argument to toggle a new
+  variable `company-auto-update-doc`.  When this variable is non-nil, it keeps
+  the documentation buffer up-to-date whenever the selection changes
+  ([#1331](https://github.com/company-mode/company-mode/discussions/1331)).
 * `company-auto-commit` and `company-auto-commit-chars` have been renamed to
   `company-insertion-on-trigger` and `company-insertion-triggers` respectively
   ([#1270](https://github.com/company-mode/company-mode/pull/1270)).
diff --git a/company.el b/company.el
index a6fa0863d0..45f15a3dcf 100644
--- a/company.el
+++ b/company.el
@@ -1340,7 +1340,14 @@ can retrieve meta-data for them."
             (and (symbolp this-command)
                  (string-match-p "\\`company-" (symbol-name this-command)))))))
 
+(defvar company-auto-update-doc nil
+  "If non-nil, company updates the doc-buffer whenever the selection changes.
+Use `company-show-doc-buffer' to toggle this variable.")
+
 (defun company-call-frontends (command)
+  (when (and company-auto-update-doc
+             (memq command '(update show)))
+    (company-show-doc-buffer))
   (cl-loop for frontend in company-frontends collect
            (condition-case-unless-debug err
                (funcall frontend command)
@@ -2821,22 +2828,36 @@ from the candidates list.")
                                  unread-command-events))
     (clear-this-command-keys t)))
 
-(defun company-show-doc-buffer ()
-  "Temporarily show the documentation buffer for the selection."
-  (interactive)
+(defun company--show-doc-buffer ()
+  "Show the documentation buffer for the selection."
   (let ((other-window-scroll-buffer)
         (selection (or company-selection 0)))
-    (company--electric-do
       (let* ((selected (nth selection company-candidates))
              (doc-buffer (or (company-call-backend 'doc-buffer selected)
-                             (user-error "No documentation available")))
+                             (if company-auto-update-doc
+                                 (company-doc-buffer
+                                  (format "%s: No documentation available"
+                                          selected))
+                               (user-error "No documentation available"))))
              start)
         (when (consp doc-buffer)
           (setq start (cdr doc-buffer)
                 doc-buffer (car doc-buffer)))
         (setq other-window-scroll-buffer (get-buffer doc-buffer))
         (let ((win (display-buffer doc-buffer t)))
-          (set-window-start win (if start start (point-min))))))))
+          (set-window-start win (if start start (point-min)))))))
+
+(defun company-show-doc-buffer (&optional toggle-auto-update)
+  "Show the documentation buffer for the selection.
+Show it temporarily unless the variable `company-auto-update-doc' is
+non-nil.  The prefix argument TOGGLE-AUTO-UPDATE toggles this variable."
+  (interactive "P")
+  (when toggle-auto-update
+    (setq company-auto-update-doc (not company-auto-update-doc)))
+  (if company-auto-update-doc
+      (company--show-doc-buffer)
+    (company--electric-do
+      (company--show-doc-buffer))))
 (put 'company-show-doc-buffer 'company-keep t)
 
 (defun company-show-location ()
diff --git a/doc/company.texi b/doc/company.texi
index 3712fe74ea..b36a415a17 100644
--- a/doc/company.texi
+++ b/doc/company.texi
@@ -353,7 +353,9 @@ Cancel @emph{company-mode} activity (@code{company-abort}).
 @cindex doc
 @findex company-show-doc-buffer
 Display a buffer with the documentation for the selected candidate
-(@w{@code{company-show-doc-buffer}}).
+(@w{@code{company-show-doc-buffer}}).  With a prefix argument it also
+toggles between temporary showing the documentation and keeping the
+documentation buffer up-to-date whenever the selection changes.
 
 @item C-w
 @kindex C-w