remove-overlays doc clarification

* lisp/subr.el (remove-overlays): Doc fix (bug#13648).

diff --git a/lisp/subr.el b/lisp/subr.el
index a58a873a33c84ff598c0fb79a7764b11f024ccb1..660367642aaf680fa7acdd08a9251d7325373e5d 100644 (file)
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -3071,9 +3071,17 @@ If MESSAGE is nil, instructions to type EXIT-CHAR are displayed there."
     o1))
 
 (defun remove-overlays (&optional beg end name val)
-  "Clear BEG and END of overlays whose property NAME has value VAL.
-Overlays might be moved and/or split.
-BEG and END default respectively to the beginning and end of buffer."
+  "Remove overlays between BEG and END that have property NAME with value VAL.
+Overlays might be moved and/or split.  If any targeted overlays
+start before BEG, the overlays will be altered so that they end
+at BEG.  Likewise, if the targeted overlays end after END, they
+will be altered so that they start at END.  Overlays that start
+at or after BEG and end before END will be removed completely.
+
+BEG and END default respectively to the beginning and end of the
+buffer.
+Values are compared with `eq'.
+If either NAME or VAL are specified, both should be specified."
   ;; This speeds up the loops over overlays.
   (unless beg (setq beg (point-min)))
   (unless end (setq end (point-max)))