bug#34708: alist-get has unclear documentation

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

Getting from an alist the value for a given key is
straightforward, obvious.  So presumably, wrt getting,
`alist-get' doesn't have to say more than that's what
it does.

But _setting_ a value for a given key in an alist is
NOT straightforward.  (An alist is not a hash table.)

Often (typically) it means just consing a new alist
entry on the front of the alist.  (That's pretty much
the main reason to use an alist.)

But you could alternatively first remove one or more
existing entry for that key from the alist and then
add the requested key+value entry.  And if you remove
_all_ such entries first then you don't necessarily
need to add the new entry to the beginning (though
you almost always would, other things being equal).

The ambiguity wrt setting means that the part of
the `alist-get' doc that talks about using it with
`setf', to set the value of the key, needs to be
very clear and correct wrt the implementation.  If
the implementation just tacks on a new entry at the
list beginning, then say so.  If it does something
else then say what that is.

It's not admissible to just say that it sets the
key to the given value.  Why?  Because of how alists
are used.  Code can very easily make use of an alist
if it knows how it is being maintained.  `alist-get'
is a general function, and its doc needs to say
something about how `setf' sets the value (what the
result is).

Similarly wrt removing an alist entry for a given
key.  Does it actually remove all such entries, or
does it just tack on a new entry with value nil at
the beginning of the list?

These things need to be specified in the doc.
Alists can be handled in more than one way when
setting and deleting keys.  The doc needs to tell
us what `setf' with `alist-get' does to realize
these things.

A user doesn't necessarily care about the "how"
details, but s?he deserves to know the "what":
What is the result of setting the value of a key
or removing a key?