bug#34708: alist-get has unclear documentation

[Drew Adams <drew.adams@oracle.com>]

> > OK.  Put it differently: it's worth documenting that updating an alist
> > entry with `setf' is a "destructive" operation: it can change list
> > structure.  Dunno whether that is already said somewhere, but even if
> > it is, a reminder wouldn't hurt.
> 
> But isn't that trivial?  How else could we add associations?

Yes, it's true of `setf' in general.  It's still
worth repeating, I think (just one opinion).
One person's "trivial" is another's "gotcha".

But apparently we don't even point this out in
the Elisp manual doc for `setf', alas.

And even for `setcdr' etc., the manual doesn't
repeat it.  It mentions it only in the parent
node, `Modifying Existing List Structure'.

`setf' is not mentioned in that node, BTW.
Perhaps some mention would make sense, saying
that when the place to be modified is a list
the list structure can be modified - it is a
so-called "destructive" operation.

"Destructive" is mentioned in node `Rearrangement',
however.  Why it's not mentioned in nodes `Setcar'
and `Setcdr' I don't know.  (Sure, those nodes do
make clear that list structure can be modified.
But they don't specifically call them "destructive"
operations.)

I suggest we document explicitly for `alist-get'
that using it as a generalized variable is a
"destructive" operation - in both the doc string
and node `Association Lists'.

Whenever we say of some function that it "is a
generalized variable suitable for use with
`setf'", I think we should add that using it to
modify a list is a "destructive" operation, i.e.,
it can change list structure.

We should be a bit more consistent.  We say
`delq' is a "destructive" operation, but we
don't say that explicitly about `delete' with
a list (node `Sets and Lists').  (We do say it
indirectly.)

I'm not crazy about the term "destructive" for
changes to list structure, BTW.  But that's the
term Emacs Lisp doc has chosen to use.  As such,
we should call it out everywhere it's applicable
- or nowhere.  It is not the case, for example,
that `setcdr' is more "destructive" than `setf'
+ `alist-get'.

Some get so excited about such "destruction"
that they make a big deal about strongly
discouraging users from using such functions.
I don't.  But I do think it's worth explicitly
making users aware of which functions can
change list structure (as well as what that
means - the consequences).