bug#34708: alist-get has unclear documentation

[Michael Heerdegen]

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

> Hi
>
> I think the sentence below is a good and short explanation for the
> doc-string.
>
> The return value can be conveniently used as a generalized variable (a
> place) to set the value associated with KEY in ALIST, like in the
> example (setf (alist-get key alist) new-value)

Thanks for the idea.  I don't think we should explain it like this
however, because when evaluating

  (setf (alist-get key alist) new-value)

the function `alist-get' is never called, so there is no return value.
Of course what is sexy about place expressions is that it looks like you
would directly set the result of a function call, but what happens is
that setf doesn't evaluate the call but analyses it and builds and
evaluates code that leads to this result.

Eric suggested to say "this form is a setf-able place" but this also
doesn't answer the question what this (form) is.  `alist-get' is not a
form, it's the name of a function.  In my opinion it would be cleaner to
say something like "the name of this function can be used to build place
expressions" or "can be used in place expressions" or so.  Better ideas
welcome.


Michael.