Re: Is it ok to sort a list of overlays destructively?

[Eli Zaretskii]

> From: Marcin Borkowski <mbork@mbork.pl>
> Cc: help-gnu-emacs@gnu.org
> Date: Wed, 28 Jul 2021 08:06:24 +0200
> 
> Would it be a good idea to say explicitly in the docstrings of both
> functions that their results may be safely modified destructively?  If
> so, I can file a bug report.

My personal opinion is that stating this fact in the doc strings of
these APIs alone makes little sense: we have many similar APIs, so
will need to say the same for most or all of them, otherwise users
will become confused.

Basically, you should assume that Emacs protects itself where that is
needed, so if it handed you a list or some other data, and nothing in
the doc string warns you against doing something with that data, you
are free to do that, and if that causes unexpected results, there's
either a documentation bug or a code bug that needs to be fixed.

That said, if you still feel like filing a bug report, please do;
perhaps my is an odd-one-out opinion.