bug#59067: 29.0.50; Exexpected overlay order in `overlays-in' return value

[Eli Zaretskii <eliz@gnu.org>]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: 59067@debbugs.gnu.org
> Date: Sun, 06 Nov 2022 07:04:54 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > I'm not sure we want to keep the old order (which AFAIU was the side
> > effect of the implementation), nor become committed to a specific
> > order.  Sorting overlays is a slowdown, and not every application
> > cares about the order.  The ones that do care can sort the overlays in
> > the order they want.
> >
> > Or maybe I'm missing something: can you explain why the order matters
> > in a couple of specific examples from Org?
> 
> You are right. `overlays-in' docstring does not give any promises.
> It is not really a big deal for Org as well (can as well sort the return
> value).
> 
> The only thing that could be useful on Emacs side is explicitly stating
> in the `overlays-in' docstring that overlay list may be in arbitrary
> order.

I'll wait for a few days for other ideas and opinions, and if nothing
pops up, I will amend the documentation (and NEWS, as this is probably
NEWS-worthy).

Thanks.