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

[Philipp]

> Am 03.06.2021 um 16:41 schrieb Stefan Monnier <monnier@iro.umontreal.ca>:
> 
>> 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.

I don't know how concrete a case you want here, but basically I'd like the 
manual to describe the semantics of

(let ((var FORM)) (setcar var VAL))

for arbitrary values of FORM (assuming that FORM returns a cons object).  
Likewise for `aset', `set', and the other object-mutating primitives.
What the semantics of such a form are depends crucially on the mutability of 
the value returned by FORM: if FORM returns an immutable object, then the 
overall form triggers undefined behavior.  In other words, the manual needs to 
provide a procedure to classify forms according to the mutability of their 
return values.

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

The Lisp manual should still make this distinction explicitly.  It can be 
derived from the structure of lists, but it's a subtle point that deserved 
reiterating.

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

I don't think there's a meaningful distinction between "possible" and "allowed" 
as far as code authors are concerned, and I don't think the manual should use 
such vague terms.  Likewise, "strongly recommended" belongs into a style guide, 
not a reference manual.  In the end, the ability to write programs boils down 
to knowing the semantics of the lexical entities of the programming language in 
question, and for that to work the semantics need to be documented.
The Info node `Mutability' isn't actually so bad in explaining these concepts 
on a conceptual level.  It says clearly that mutable and immutable objects 
exist, and that attempting to mutate an immutable object triggers undefined 
behavior.  (I dislike the manual's usage of the phrase "should not" to mean 
"undefined behavior", but that's a different can of worms that we don't need to 
open here.)  I don't want to introduce new concepts or terminology here.  
What's missing is really what this bug is asking for: a procedure to derive the 
mutability of objects from the forms that produce them.  The `Mutability' node 
documents this for some objects, but not all.