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

[Stefan Monnier via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

> 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.

While I can kinda see where you're going, it's still pretty fuzzy to me.
I think it would be more clear if you could give concrete cases where
you'd want to use such information.

> 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.

This is a pervasive issue, much more pervasive than `list` and that
applies to pretty much all programming languages.  So I don't think it
has its place in the doc of `list`.

I hope the box diagrams of the intro to ELisp can be considered
a documentation of this phenomenon.

> it must be possible for programmers to derive whether (setcar var ...)
> is allowed from some set of rules plus the docstring of the function.

[ Aha: here's is an example!  ]

Mutability says whether it is *possible*, rather than whether it's
*allowed*.  Most (all?) cons cells are mutable, but it is strongly
recommended to refrain from mutating most cons cells (because it
can/will have unexpected consequences because that same cons cell is
also used elsewhere).

So what you're asking here is not exactly mutability but something
slightly different, which is not very well defined nor
documented, indeed.


        Stefan