Re: emacs-27 eebfb72 1/2: Document constant vs mutable objects better

[Paul Eggert]

On 4/18/20 2:24 PM, Štěpán Němec wrote:

> > -When a variable is set to a list with a function such as @code{setq},
> > +When a variable is set to a list via @code{setq},
>
> I understand you wanted to avoid implying that `setq' was a function,
> but how about "setq or a similar function",

Thanks, that sounds good. See attached patch. Unless otherwise specified, the 
patch simply adopts your other suggestions.
> > -However, the other arguments (all but the last) must be lists.
> > +However, the other arguments (all but the last) must be mutable lists.
>                                                             ^^^^^^^
> I don't think this is a good formulation, for reasons explained at the
> bottom.

See below.

> > -(memq 1.2 '(1.1 1.2 1.3))  ; @r{@code{1.2} and @code{1.2} are not @code{eq}.}
> > +(memq (list 2) '((1) (2)))  ; @r{@code{(list 2)} and @code{(2)} are not 
> > @code{eq}.}
>
> I think this is missing the point, which is numeric comparison with `eq'
> vs `eql' ("floating-point elements are compared by value"); no
> mutability issues involved.

You're right that my change missed the point and needs to be fixed. However, 
mutability issues are relevant here: mutability came up partly because the Lisp 
compiler is free to share structure of the original program and this means those 
two instances of 1.2 might be eq. The attached patch reverts the abovementioned 
change but adds commentary about why that memq call might not return nil.

> > -(memq '(2) '((1) (2)))    ; @r{@code{(2)} and @code{(2)} are not @code{eq}.}
> > +(memq (list 2) '((1) (2)))    ; @r{@code{(list 2)} and @code{(2)} are not 
> > @code{eq}.}
>
> Not sure about this, either.

It's the same point as the previous one.  The two instances of (2) in the old 
example might be eq so the old example might yield non-nil. But the (list 2) and 
the quoted (2) in the revised example cannot be eq, and this corrects the example.

> > > -(assq "simple leaves" leaves)
> > > +(assq (copy-sequence "simple leaves") leaves)
> > >       @result{} nil
> > > -(assoc "simple leaves" leaves)
> > > +(assoc (copy-sequence "simple leaves") leaves)
>
> This seems strange to me. Using `copy-sequence' just to get a key for
> comparison?

The copy-sequence is needed to ensure that the assq/assoc string key argument is 
not eq to the string within the alist argument. The attached patch adds a 
comment "The @code{copy-sequence} means the keys are not @code{eq}."

> IOW, "mutable" and "safely
> mutable"/"mutating it is a good idea" should be distinguished.

The attached patch makes that distinction in a new section "Constants and 
mutability" that I hope clarifies some of the issues here. While writing this, I 
noticed that for Elisp we needn't separate the three notions 
(not-mutable-and-this-is-checked, not-safe-to-mutate, safely-mutable) 
everywhere; all we need to do is describe those notions in one spot, and 
everywhere else we can just use the term "mutable" for safely-mutable and the 
term "constant" for everything else.

Thanks for your detailed comments and suggestions. Further comments are welcome 
of course.

0001-Improve-mutability-documentation.patch
Description: Text Data