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

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

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