Clarify usage and dependencies between several Flyspell features

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

1 files changed, 11 insertions, 3 deletions

diff --git a/lisp/textmodes/flyspell.el b/lisp/textmodes/flyspell.el
index b6c8ac393c6..5726bd82cb9 100644
--- 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)