bug#34708: alist-get has unclear documentation

[Michael Heerdegen]

Phil Sainty <psainty@orcon.net.nz> writes:

> Agreed.  I think the remove syntax is all but unreadable:
>
> (setf (alist-get KEY LIST t t) t)
>
> to remove items from LIST with key eq to KEY.
>
> Unless accompanied by comments, I do not think that meaning obvious
> at all.
>
> This variant gives a better idea...
>
> (setf (alist-get KEY LIST :remove :remove) :remove)

Yes, the syntax is a bit weird.  I think I would prefer to write it as

  (setf (alist-get key my-alist nil 'remove) nil)

The syntax also makes some sense: If you set the association of KEY to
the default that `alist-get' would return when the entry would not be
not found, the entry can be removed.  But I agree we should add such an
example, since not everybody wants to meditate over why this makes sense
in order to remember the syntax.


Michael.