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

[Philipp]

> Am 05.06.2021 um 17:15 schrieb Stefan Monnier <monnier@IRO.UMontreal.CA>:
> 
>> 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),

I'm counting almost 100 occurrences of the words "undefined" or "unspecified" 
in the reference manual, so this isn't really new terminology.  It's even used 
in the manual directly for this purpose:

   If a program attempts to change objects that should not be
   changed, the resulting behavior is undefined [...]

The remaining weirdness here is saying "objects that should not be changed" 
instead of "immutable objects".
Most programming languages have some notion of "undefined" or "unspecified", 
often to allow optimizations or multiple implementations.  While there are 
downsides to introducing such behavior, often it's a reasonable compromise 
between underspecifying and overspecifying the language.
In this case, the manual already explains in a footnote that the current 
behavior is undesirable and Emacs Lisp should move into a direction where 
attempting to mutate immutable objects signals an error (thereby removing the 
undefined behavior).

> but I'd
> say that using `setcar` above is risky because the user has no guarantee
> about what it may impact.

I think that a word like "risky" has no place in a reference manual.  What does 
that even mean?  What are the risks?  Why introduce such vague and confusing 
terminology to begin with?  How would this help Emacs Lisp programmers?

> 
> I think the rule is basically, that you should only ever use `setc[ad]r`
> on cons cells you yourself created.

What does "should" mean here?  What happens if users don't follow this 
"recommendation"?  How do they identify "cons cells you yourself created"?
Again, I think such terminology brings up more questions than it answers.

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

Then let's document that (while avoiding terms such as "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.

Good.  Then let's document that!

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

Can we find a wording that we agree on and put it into the manual?