bug#34708: alist-get has unclear documentation

[Michael Heerdegen <michael_heerdegen@web.de>]

"Miguel V. S. Frasson" <mvsfrasson@gmail.com> writes:

> I can't imagine how to *set* anything with alist-get. It seams to me
> that it just use the value of ALIST for look up, so talk about
> generalized variables is meaningless to me here.

You use it like this: say variable V is bound to an alist, then you can
do (setf (alist-get key V) value).  After that, (alist-get key V) will
evaluate to VALUE, so you have "set" that place.  In the general case, V
can also be a generalized variable, e.g. (car SOMETHING-ELSE).

To replace the word "this" with something better is not so easy.  We
could write "The name of this function can be used to build expressions
that can be used as a generalized variable", but I doubt it will make
things clearer for somebody not familiar with the concept of generalized
variables.  Using this function name to build place expressions is not
different from using other function names that allow to be used for
generalized variables.

I would rather go with an example, which I think is justified because
using this function name in place expressions is the canonical way to
modify alists and people need to use it (there is no `alist-put') no
matter if they are familiar with generalized variables.

Michael.