[elpa] master b6dc924 03/10: spinner: Document new functionality

[Artur Malabarba]

branch: master
commit b6dc9242e1ab5a1edee1531b1b282b9c18f5ad39
Author: Artur Malabarba <address@hidden>
Commit: Artur Malabarba <address@hidden>

    spinner: Document new functionality
---
 README.org |   44 ++++++++++++++++++++++++++++++++++-----
 spinner.el |   66 +++++++++++++++++++++++++++++++++++++++++++++--------------
 2 files changed, 88 insertions(+), 22 deletions(-)

diff --git a/README.org b/README.org
index b398ed0..9eab94f 100644
--- a/README.org
+++ b/README.org
@@ -8,13 +8,11 @@ Add spinners and progress-bars to the mode-line for ongoing 
operations.
 
 * Usage
 
-1. Add ~(spinner "VERSION")~ to your package’s dependencies.
+First of all, don’t forget to add ~(spinner "VERSION")~ to your package’s 
dependencies.
 
-2. Call ~(spinner-start)~ and a spinner will be added to the mode-line.
-
-3. Call ~(spinner-stop)~ on the same buffer when you want to remove it.
-
-* Behavior
+** Major-modes
+1. Just call ~(spinner-start)~ and a spinner will be added to the mode-line.
+2. Call ~(spinner-stop)~ on the same buffer when you want to remove it.
 
 The default spinner is a line drawing that rotates. You can pass an
 argument to ~spinner-start~ to specify which spinner you want. All
@@ -25,3 +23,37 @@ a few examples for you to try:
 - ~(spinner-start 'minibox)~
 - ~(spinner-start 'moon)~
 - ~(spinner-start 'triangle)~
+
+You can also define your own as a vector of strings (see the examples
+in ~spinner-types~).
+
+** Minor-modes
+Minor-modes can create a spinner (that can be added to the mode’s
+lighter) with ~spinner-make-construct~. They can then start the
+spinner by setting a variable and calling ~spinner-start-timer~.
+Finally, they can stop the spinner (and the timer) by just setting the
+same variable to nil.
+
+Here’s an example for a minor-mode named ~foo~.
+#+begin_src emacs-lisp
+(defvar foo--spinner nil)
+(defvar foo--timer nil)
+(defconst foo--lighter
+  (list " foo"
+        (spinner-make-construct 'foo--spinner 'foo--timer)))
+
+(defun foo--start-spinning ()
+  "Start foo's spinner."
+  (setq foo--spinner
+        (cdr (assq 'horizontal-bar spinner-types)))
+  (spinner-start-timer 'foo--spinner 'foo--timer))
+
+(defun foo--stop-spinning ()
+  "Stop foo's spinner"
+  (setq foo--spinner nil))
+#+end_src
+
+This will use the ~horizontal-bar~ spinner, but you can use anything
+defined in the ~spinner-types~ variable, or even define your own.
+
+
diff --git a/spinner.el b/spinner.el
index a40005c..47dad2b 100644
--- a/spinner.el
+++ b/spinner.el
@@ -25,28 +25,62 @@
 ;; 1 Usage
 ;; ═══════
 ;;
-;; 1. Add `(spinner "VERSION")' to your package’s dependencies.
+;;   First of all, don’t forget to add `(spinner "VERSION")' to your
+;;   package’s dependencies.
 ;;
-;; 2. Call `(spinner-start)' and a spinner will be added to the
-;; mode-line.
 ;;
-;; 3. Call `(spinner-stop)' on the same buffer when you want to remove
-;; it.
+;; 1.1 Major-modes
+;; ───────────────
 ;;
+;;   1. Just call `(spinner-start)' and a spinner will be added to the
+;;      mode-line.
+;;   2. Call `(spinner-stop)' on the same buffer when you want to remove
+;;      it.
 ;;
-;; 2 Behavior
-;; ══════════
+;;   The default spinner is a line drawing that rotates. You can pass an
+;;   argument to `spinner-start' to specify which spinner you want. All
+;;   possibilities are listed in the `spinner-types' variable, but here are
+;;   a few examples for you to try:
 ;;
-;; The default spinner is a line drawing that rotates. You can pass an
-;; argument to `spinner-start' to specify which spinner you want. All
-;; possibilities are listed in the `spinner-types' variable, but here are
-;; a few examples for you to try:
+;;   • `(spinner-start 'vertical-breathing 10)'
+;;   • `(spinner-start 'minibox)'
+;;   • `(spinner-start 'moon)'
+;;   • `(spinner-start 'triangle)'
 ;;
-;; • `(spinner-start 'vertical-breathing 10)'
-;; • `(spinner-start 'minibox)'
-;; • `(spinner-start 'moon)'
-;; • `(spinner-start 'triangle)'
-
+;;   You can also define your own as a vector of strings (see the examples
+;;   in `spinner-types').
+;;
+;;
+;; 1.2 Minor-modes
+;; ───────────────
+;;
+;;   Minor-modes can create a spinner (that can be added to the mode’s
+;;   lighter) with `spinner-make-construct'. They can then start the
+;;   spinner by setting a variable and calling `spinner-start-timer'.
+;;   Finally, they can stop the spinner (and the timer) by just setting the
+;;   same variable to nil.
+;;
+;;   Here’s an example for a minor-mode named `foo'.
+;;   ┌────
+;;   │ (defvar foo--spinner nil)
+;;   │ (defvar foo--timer nil)
+;;   │ (defconst foo--lighter
+;;   │   (list " foo"
+;;   │         (spinner-make-construct 'foo--spinner 'foo--timer)))
+;;   │
+;;   │ (defun foo--start-spinning ()
+;;   │   "Start foo's spinner."
+;;   │   (setq foo--spinner
+;;   │         (cdr (assq 'horizontal-bar spinner-types)))
+;;   │   (spinner-start-timer 'foo--spinner 'foo--timer))
+;;   │
+;;   │ (defun foo--stop-spinning ()
+;;   │   "Stop foo's spinner"
+;;   │   (setq foo--spinner nil))
+;;   └────
+;;
+;;   This will use the `horizontal-bar' spinner, but you can use anything
+;;   defined in the `spinner-types' variable, or even define your own.
 
 ;;; Code:
 (require 'cl-lib)