bug#34708: alist-get has unclear documentation

[Eric Abrahamsen]

On 03/03/19 07:51 AM, Drew Adams wrote:

[...]

>> 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.

Well I used "form" because it _is_ the form -- (alist-get KEY ALIST) --
that is the setf-able place, not the function/macro/name of the
function. At least as far as the coder is concerned.

> Yes wrt the substance (content). But an active
> phrasing is often better than the passive "__ can
> be used". Say what this does by saying what you
> can do with it.
>
> You can use function `alist-get' in a PLACE-expression
> argument to `setf'. In this role it specifies an
> alist element whose value `setf' sets:

> (setf (alist-get KEY ALIST) NEW-VALUE)
>
> Here, `setf' sets the value part of an element
> of ALIST whose key is KEY to NEW-VALUE.

But I like the above better anyway!