From f6a641ebbcec20cbe040ddb17c2ba4638465e191 Mon Sep 17 00:00:00 2001
From: Boris Buliga <boris@d12frosted.io>
Date: Sat, 15 Feb 2020 14:28:24 +0200
Subject: [PATCH] rename 'stop -> 'break and document interface

---
 flyspell-correct.el           | 35 ++++++++++++++++++++++++++++-------
 test/test-flyspell-correct.el |  7 ++++---
 2 files changed, 32 insertions(+), 10 deletions(-)

diff --git a/flyspell-correct.el b/flyspell-correct.el
index 036a026..14c8e9e 100644
--- a/flyspell-correct.el
+++ b/flyspell-correct.el
@@ -61,10 +61,31 @@
 
 (defcustom flyspell-correct-interface #'flyspell-correct-dummy
   "Interface for `flyspell-correct-at-point'.
-It has to be function that accepts two arguments - candidates and
-misspelled word. It has to return either replacement word
-or (command, word) tuple that will be passed to
-`flyspell-do-correct'."
+
+`flyspell-correct-interface' is a function accepting two arguments:
+
+  - candidates for correction (list of strings)
+  - misspelled word (string)
+
+Result must be either a string (replacement word) or a cons of a
+command and a string (replacement word), where the command is one
+of the following:
+
+  - skip - do nothing to misspelled word, in rapid mode used for
+    jumping to the next (or previous) misspelled word
+
+  - break - do nothing to misspelled word, break from rapid mode
+
+  - save - replace misspelled word with replacement word and save
+    it to the personal dictionary
+
+  - session - replace misspelled word with replacement word and
+    save it to the session dictionary (correction will be
+    discarded upon quitting Emacs)
+
+  - buffer - replace misspelled word with replacement word and
+    save it to the buffer dictionary (added to the bottom of
+    buffer)"
   :group 'flyspell-correct
   :type 'function)
 
@@ -147,7 +168,7 @@ Adapted from `flyspell-correct-word-before-point'."
                   ;; Some interfaces actually eat 'C-g' so it's impossible to
                   ;; stop rapid mode. So when interface returns nil we treat it
                   ;; as a stop. Fixes #60.
-                  (unless res (setq res (cons 'stop word)))
+                  (unless res (setq res (cons 'break word)))
                   (cond
                    ((stringp res)
                     (flyspell-do-correct
@@ -156,7 +177,7 @@ Adapted from `flyspell-correct-word-before-point'."
                     (let ((cmd (car res))
                           (wrd (cdr res)))
                       (unless (or (eq cmd 'skip)
-                                  (eq cmd 'stop))
+                                  (eq cmd 'break))
                         (flyspell-do-correct
                          cmd poss wrd cursor-location start end opoint)
                         (unless (string-equal wrd word)
@@ -286,7 +307,7 @@ until all errors in buffer have been addressed."
 	                          (/= (mark t) (point)))
                     (push-mark (point) t))
                   (when (or (not rapid)
-                            (eq (car-safe res) 'stop))
+                            (eq (car-safe res) 'break))
                     (setq overlay nil)))))))
 
         (when incorrect-word-pos
diff --git a/test/test-flyspell-correct.el b/test/test-flyspell-correct.el
index 43477b2..62c23e0 100644
--- a/test/test-flyspell-correct.el
+++ b/test/test-flyspell-correct.el
@@ -525,11 +525,12 @@ Simply passed WORD to `correct-word' mock."
          (expect 'correct-word :to-have-been-called-with "versiuns")
          (expect 'correct-word :to-have-been-called-with "werk")))))
 
-  (describe "stop"
+  (describe "break"
 
     (before-each
-      (spy-on 'correct-interface :and-call-through)
-      (spy-on 'correct-word :and-return-value nil))
+     (spy-on 'correct-interface :and-call-through)
+     ;; imitate C-g
+     (spy-on 'correct-word :and-return-value nil))
 
     (it "call correct interface only once with backward direction"
       (with-mistakes|cursor-after