bug#60399: 30.0.50; Usage of `isearch-open-invisible-temporary' is not documented

[Eli Zaretskii <eliz@gnu.org>]

> Cc: 60399@debbugs.gnu.org
> From: Ihor Radchenko <yantar92@posteo.net>
> Date: Sat, 31 Dec 2022 13:03:11 +0000
> 
> Juri Linkov <juri@linkov.net> writes:
> 
> >>       ;; 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.
> >>       (funcall  (overlay-get ov 'isearch-open-invisible-temporary)  ov nil)
> >>
> >> However, it appears that deleting the passed overlay is, in fact,
> >> prohibited. (manifested in
> >> https://orgmode.org/list/87pmc4smdg.fsf@fastmail.fm)
> >>
> >> Is there some detailed information about this feature available somewhere?
> >
> > I don't know about this function more than you can read from source code,
> > but can find two mentions in (info "(elisp) Invisible Text") and
> > (info "(elisp) Overlay Properties").
> 
> Manual provides no more information.
> 
> Would it make sense to mention that overlays passed as an argument of
> 'isearch-open-invisible-temporary function must not be destroyed?

I've now added a warning to this effect to the comments in
isearch-open-overlay-temporary, and I'm therefore closing this bug.