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

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

I don't think we want to labels this as "undefined" or "invalid"
(Emacs and Emacs Lisp tries hard to avoid enforcing abstraction
boundaries, and relies instead on softer forms of discipline), but I'd
say that using `setcar` above is risky because the user has no guarantee
about what it may impact.

I think the rule is basically, that you should only ever use `setc[ad]r`
on cons cells you yourself created.  But indeed the manual fails to
document which functions guarantee to return "fresh" new cells, which
makes it hard to know which cells "you yourself created".

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

All of them.

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

I think we have (3).


        Stefan