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

[Lars Ingebrigtsen <larsi@gnus.org>]

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