bug#43836: 27.1; Doc string of `alist-get'

bug#43836: 27.1; Doc string of `alist-get'

[Drew Adams]

The doc string is less clear in 27.1 than it was in 26.3.

Instead of saying that a generalized variable is involved, it says:

  You can use `alist-get' in PLACE expressions.  This will modify
  an existing association (more precisely, the first one if
  multiple exist), or add a new element to the beginning of ALIST,
  destructively modifying the list stored in ALIST.

A user can a least look up "generalized variable" in Emacs 26.  The
Emacs 27 version just refers to "PLACE expressions", which is unclear
and can't be looked up easily.  And why is PLACE uppercase, which
indicates that it's something in the calling sequence or is otherwise
defined in the doc string somehow?

It's also not clear how _adding_ a new element to the beginning of ALIST
destructively modifies it.  Does it really mean setting the car of ALIST
to a different element, not adding an element?

bug#43836: 27.1; Doc string of `alist-get'

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> The doc string is less clear in 27.1 than it was in 26.3.
>
> Instead of saying that a generalized variable is involved, it says:
>
>   You can use `alist-get' in PLACE expressions.  This will modify
>   an existing association (more precisely, the first one if
>   multiple exist), or add a new element to the beginning of ALIST,
>   destructively modifying the list stored in ALIST.
>
> A user can a least look up "generalized variable" in Emacs 26.  The
> Emacs 27 version just refers to "PLACE expressions", which is unclear
> and can't be looked up easily.  And why is PLACE uppercase, which
> indicates that it's something in the calling sequence or is otherwise
> defined in the doc string somehow?

I've now reintroduced "generalized variable" and downcased PLACE in
Emacs 28.

> It's also not clear how _adding_ a new element to the beginning of ALIST
> destructively modifies it.  Does it really mean setting the car of ALIST
> to a different element, not adding an element?

The example that follows on clarifies what's meant here.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#43836: 27.1; Doc string of `alist-get'

[Drew Adams]

> > It's also not clear how _adding_ a new element to the beginning of ALIST
> > destructively modifies it.  Does it really mean setting the car of ALIST
> > to a different element, not adding an element?
> 
> The example that follows on clarifies what's meant here.

Not really.  Not clear to me what's meant.

The first example adds (b . 2) to the front of the
alist.  OK.  But does it destructively modify the
list?  Or does `foo' just point to a new list (new
cons) whose cdr is the old list?

(I'm sure that some operations with `alist-get' do
modify list structure.  But I don't see how adding
an element to the front of the list does that.)

And how do you add an element (b . 3) to the front
of an alist that has an element (b . 2)?  An alist
can have multiple elements with the same key.

Sorry, but just what the behavior is for a place
expression that uses `alist-get' isn't clear to me
from that doc string, at all.

I have the same questions for the description at
(elisp) `Association Lists'.

This is apparently a useful function, and a bit
complex.  I suspect the doc isn't doing it justice,
but not understanding the actual behavior I can
only wonder.