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

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

> Am 04.06.2021 um 15:01 schrieb 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.

To provide a more concrete example:

Assume you have the following (nonsense) function, with unknown implementation:

(defun my-cons ()
  "Return a cons cell consisting of the integers 1 and 2."
  ...)

I. Given only that information and the manual, is the following code valid (i.e. can't trigger undefined behavior in any case)?

(setcar (my-cons) 5)

II. Which of the following implementations of `my-cons' is correct (i.e. follows the rules of Emacs Lisp as described in the manual)?

(a)
(defun my-cons ()
  "Return a cons cell consisting of the integers 1 and 2."
  '(1 . 2))

(b)
(defun my-cons ()
  "Return a cons cell consisting of the integers 1 and 2."
  (cons 1 2)

(c)
(defun my-cons ()
  "Return a cons cell consisting of the integers 1 and 2."
  (if (eq (random 2) 0) '(1 . 2) (cons 1 2))

From what I can see there are four options:

1. Unless otherwise specified, objects are mutable.  Then the `setcar' form is valid, and only implementation (b) is correct.
2. Unless otherwise specified, objects are immutable.  Then the `setcar' form always triggers undefined behavior, and only implementation (a) is correct.
3. Unless otherwise specified, the objects that forms return are of unspecified mutability (i.e. they can be mutable or immutable).  Then the `setcar' form is invalid because the caller of `my-cons' can't assume that its return value is mutable, and all three implementations of `my-cons' are correct.
4. Mutability of the return object must be specified in all cases.  Then none of the implementations is correct, since none of them specifies the mutability of the returned cons object.

What I'd like here (among other things) is a statement in the manual which of the options (1)-(4) is the correct one.  (Or are there other options?)