bug#34708: alist-get has unclear documentation

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

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

Lose "conveniently", please.

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

Yes.  (But that text didn't say it was called, and
it didn't mention a return value.)

`setf' is a macro.  Its PLACE arg serves as a
_specification_ of a place (a "generalized
variable") whose value is to be set.  And "set"
means create or update.

It's not really about `alist-get' here; it's
about `setf'.  `alist-get' itself has nothing
to do with using a generalized variable.

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

Yes.  But that's "just" plumbing.  It's not
important to explain that here, I think.

In terms of describing the role of `alist-get'
as a `setf' place it's not relevant, at a first
approximation.

That `setf' doesn't call `alist-get' but instead
analyses the spec and builds code that does the
right thing is not necessary for getting the main
point that `alist-get' can be used with `setf' to
specify an alist element to create or update.

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

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.

It's important to not give the impression that
there must be an _existing_ element with KEY.
Showing an example can help dispel that mistake.

   (setq foo ())
   (setf (alist-get 'a foo) 1
         (alist-get 'b foo) 2)

   C-h v foo ; ==> ((b . 2) (a . 1))