bug#43557: 28.0.50; Please document which objects are mutable and which are not

[Philipp Stephani <p.stephani2@gmail.com>]

Am Do., 15. Okt. 2020 um 17:34 Uhr schrieb Lars Ingebrigtsen <larsi@gnus.org>:
>
> Philipp Stephani <p.stephani2@gmail.com> writes:
>
> > The "Mutability" section in the ELisp manual mentions that there are
> > mutable and immutable objects, but (besides giving a few examples)
> > doesn't document which objects are actually mutable.  At the very least,
> > there should be a list of functions that are guaranteed to return
> > mutable objects, and a statement about the mutability of function return
> > values in general.
>
> Reading the section, it seems pretty clear to me, and outlines the cases
> where you can't assume mutability (even if the objects may appear to be
> mutable).

I disagree. "Pretty clear" would mean "allowing the reader to classify
each Lisp expression w.r.t. the mutability of its value", and as the
section only gives a few examples, it can't do that. What it should do
in addition is provide rules on how to classify any given Lisp
expression. Each possible Lisp expression has to fall into exactly one
of three categories:
- The value is mutable.
- The value is immutable.
- It is unspecified whether the value is mutable or immutable.
Given that we can't document this for every Lisp function in
existence, we need to pick some default, and document that default in
the manual. Also, we need to document the cases where the default
doesn't apply, either in the manual or in function docstrings.
I'm happy to add the necessary documentation, but for that we first
need a decision what the default is, and what the exceptions are.

>
> I'm not sure a list of mutable objects is a well-defined request, and
> there are very few functions that can promise to return a mutable
> object.  (I mean, (list 1 2 immutable-list) is mutable, but can contain
> elements that aren't.)

Then the docstring of `list' and the ELisp manual should say that. The
difference between shallow and deep immutability might not be clear to
all readers, so it's important that it's documented as well.

>
> So I'm not sure whether what you're requesting is feasible.

It must be feasible, otherwise programming in ELisp becomes, strictly
speaking, impossible. Given code such as
(let ((var (some-list-returning-function ...))) ...)
it must be possible for programmers to derive whether (setcar var ...)
is allowed from some set of rules plus the docstring of the function.
This is not some theoretical problem: This bug was triggered by a code
review where the author and reviewer disagreed what could be assumed
about the mutability of the return value of arbitrary functions, so
fixing this bug has very practical consequences.