[elpa] externals/marginalia c8c3f87 045/241: Rename toggle -> cycle, improve documenation

[Stefan Monnier]

branch: externals/marginalia
commit c8c3f87c03101a0f18a0c923a85ffe4a70f23241
Author: Omar Antolín <omar.antolin@gmail.com>
Commit: Omar Antolín <omar.antolin@gmail.com>

    Rename toggle -> cycle, improve documenation
---
 README.md     |  3 ++-
 marginalia.el | 24 ++++++++++++++++--------
 2 files changed, 18 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 89c0b7c..4d7a2be 100644
--- a/README.md
+++ b/README.md
@@ -35,6 +35,7 @@ specified by the variable `marginalia-classifiers`.
   ;; Prefer richer, more heavy, annotations over the lighter default variant.
   ;; E.g. M-x will show the documentation string additional to the keybinding.
   ;; By default only the keybinding is shown as annotation.
-  ;; Note that there is the command `marginalia-toggle-annotators` to switch 
between the annotators.
+  ;; Note that there is the command `marginalia-cycle-annotators` to 
+  ;; switch between the annotators.
   (setq marginalia-annotators '(marginalia-annotators-heavy 
marginalia-annotators-light)))
 ~~~
diff --git a/marginalia.el b/marginalia.el
index c6c70d4..01fde0d 100644
--- a/marginalia.el
+++ b/marginalia.el
@@ -98,10 +98,15 @@
   '(marginalia-annotators-light marginalia-annotators-heavy)
   "Choose an annotator association list for minibuffer completion.
 The first entry in the list is used for annotations.
-You can toggle between the annotators using `marginalia-toggle-annotators'.
-Annotations are only shown if `marginalia-mode' is enabled."
+You can cycle between the annotators using `marginalia-cycle-annotators'.
+Annotations are only shown if `marginalia-mode' is enabled.
+An entry of nil disables marginalia's annotations (leaving you
+only with the annotations that come with Emacs) without disabling
+`marginalia-mode'; this can be convenient for users of
+`marginalia-cycle-annotators'."
   :type '(repeat (choice (const :tag "Light" marginalia-annotators-light)
                          (const :tag "Heavy" marginalia-annotators-heavy)
+                         (const :tag "None" nil)
                          (symbol :tag "Other")))
   :group 'marginalia)
 
@@ -419,19 +424,22 @@ Remember `this-command' for annotation."
     ;; Replace the metadata function.
     (advice-add #'completion-metadata-get :before-until 
#'marginalia--completion-metadata-get)))
 
-;; If you want to toggle between annotators while being in the minibuffer, the 
completion-system
+;; If you want to cycle between annotators while being in the minibuffer, the 
completion-system
 ;; should refresh the candidate list. Currently there is no support for this 
in marginalia, but it
-;; is possible to advice the `marginalia-toggle-annotators' function with the 
necessary refreshing
+;; is possible to advise the `marginalia-cycle-annotators' function with the 
necessary refreshing
 ;; logic. See the discussion in https://github.com/minad/marginalia/issues/10 
for reference.
 ;;;###autoload
-(defun marginalia-toggle-annotators ()
-  "Toggle between annotators in `marginalia-annotators'."
+(defun marginalia-cycle-annotators ()
+  "Cycle between annotators in `marginalia-annotators'.
+If called from the minibuffer the annotator cycling is local,
+that it is, it does not affect subsequent minibuffers.  When called
+from a regular buffer the effect is global."
   (interactive)
   (let ((annotators (append (cdr marginalia-annotators)
                             (list (car marginalia-annotators)))))
-    ;; If `marginalia-toggle-annotators' has been invoked from inside the 
minibuffer, only change
+    ;; If `marginalia-cycle-annotators' has been invoked from inside the 
minibuffer, only change
     ;; the annotators locally. This is useful if the command is used as an 
action. If the command is
-    ;; not triggered from inside the minibuffer, toggle the annotator 
globally. Hopefully this is
+    ;; not triggered from inside the minibuffer, cycle the annotator globally. 
Hopefully this is
     ;; not too confusing.
     (if (minibufferp)
         (setq-local marginalia-annotators annotators)