Improve documentation of 'isearch-open-overlay-temporary'

* lisp/isearch.el (isearch-open-overlay-temporary): Document that
the overlay passed to the 'isearch-open-invisible-temporary'
function cannot be deleted too early.  (Bug#60399)

diff --git a/lisp/isearch.el b/lisp/isearch.el
index ba67cce841a878684f3afe4d3336f6abb4a1804a..d20d816a428c980d98b168e31cab5731da62fbb3 100644 (file)
--- a/lisp/isearch.el
+++ b/lisp/isearch.el
@@ -3723,8 +3723,14 @@ Optional third argument, if t, means if fail just return nil (no error).
 (defun isearch-open-overlay-temporary (ov)
   (if (not (null (overlay-get ov 'isearch-open-invisible-temporary)))
       ;; Some modes would want to open the overlays temporary during
-      ;; isearch in their own way, they should set the
-      ;; `isearch-open-invisible-temporary' to a function doing this.
+      ;; isearch in their own way, they should set the overlay's
+      ;; `isearch-open-invisible-temporary' property to a function
+      ;; doing this.
+      ;; Warning: if your code uses this technique, it should not
+      ;; delete the overlay passed to that function, since the values
+      ;; of the `invisible' property will be recorded on that overlay,
+      ;; to be restored after isearch is done with the text hidden by
+      ;; the overlay.
       (funcall  (overlay-get ov 'isearch-open-invisible-temporary)  ov nil)
     ;; Store the values for the `invisible' property, and then set it to nil.
     ;; This way the text hidden by this overlay becomes visible.