Clarify usage and dependencies between several Flyspell features

* lisp/textmodes/flyspell.el (flyspell-region)
(flyspell-small-region, flyspell-persistent-highlight):
Documentation improvements.  (Bug#32142)

diff --git a/lisp/textmodes/flyspell.el b/lisp/textmodes/flyspell.el
index b6c8ac393c6d2afabe42a5313c104ac7b96b1c6e..5726bd82cb9436d7bda4bd9d8b71486a10d4f58e 100644 (file)
--- a/lisp/textmodes/flyspell.el
+++ b/lisp/textmodes/flyspell.el
@@ -138,7 +138,9 @@ This variable specifies how far to search to find such a duplicate.
   "Non-nil means misspelled words remain highlighted until corrected.
 If this variable is nil, only the most recently detected misspelled word
 is highlighted, and the highlight is turned off as soon as point moves
-off the misspelled word."
+off the misspelled word.
+
+Make sure this variable is non-nil if you use `flyspell-region'."
   :group 'flyspell
   :type 'boolean)
 
@@ -1368,7 +1370,10 @@ language."
 ;;*    flyspell-small-region ...                                        */
 ;;*---------------------------------------------------------------------*/
 (defun flyspell-small-region (beg end)
-  "Flyspell text between BEG and END."
+  "Flyspell text between BEG and END.
+
+This function is intended to work on small regions, as
+determined by `flyspell-large-region'."
   (save-excursion
     (if (> beg end)
        (let ((old beg))
@@ -1639,7 +1644,10 @@ The buffer to mark them in is `flyspell-large-region-buffer'."
 ;;*---------------------------------------------------------------------*/
 ;;;###autoload
 (defun flyspell-region (beg end)
-  "Flyspell text between BEG and END."
+  "Flyspell text between BEG and END.
+
+Make sure `flyspell-mode' is turned on if you want the highlight
+of a misspelled word removed when you've corrected it."
   (interactive "r")
   (ispell-set-spellchecker-params)  ; Initialize variables and dicts alists
   (if (= beg end)