bug#34708: alist-get has unclear documentation

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

> > > (progn
> > >   (setq my-alist '((a . 1) (b . 2)))
> > >   (push (car my-alist) my-alist)
> > >   ;; my-alist ==> (#1=(a . 1) #1# (b . 2))
> > >   (setf (alist-get 'a my-alist nil 'remove) nil))
> > >   ;; my-alist ==> ((b . 2))
> > >
> > > This is because the code uses delq to delete a found cons, and delq
> > > removes all `eq' elements.
> > >
> > > Is it worth to document or change that?
> >
> > Sounds like an implementation/design artifact.  If that will stay as
> > part of the design then yes, I'd say such behavior needs to be
> > documented.
> 
> BTW with a different viewpoint, when you use
>  (setcdr (assoc 'a my-alist) 17)
> 
> on the above degenerated alist you also change _both_ of the 'a
> associations, so one could argue that the `alist-get' setter behaves
> correctly when removing both: there are not two 'a associations in
> MY-ALIST but the same one has just been added two times, so it's correct
> to remove both of them.

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.