bug#23548: 25.0.93; lists.texi (alist-get): Document optional arg 'remove'.

[Eli Zaretskii]

> Date: Mon, 16 May 2016 23:13:35 +0900 (JST)
> From: Tino Calancha <f92capac@gmail.com>
> 
> * doc/lispref/lists.texi (alist-get): Document optional arg. 'remove'.
> Rename second argument to 'alist'.

You renamed it only in the @defun line.  The description still uses
'value', so there's now a disconnect.

> +@defun alist-get key alist &optional default remove
>   This function is like @code{assq}, but instead of returning the entire
>   association for @var{key}, @code{(@var{key} . @var{value})}, it
>   returns just the @var{value}.  It returns @var{default} if @var{key}
>   is not found in @var{alist}, defaulting to @code{nil} if @var{default}
>   is omitted.
> +
> +When using this function to set the value at @var{key}
> +to @var{new-val}, if @var{remove} evaluates non-@code{nil} and
> +@var{default} is @code{eql} to @var{new-val}, then the entry at
> +@var{key} is deleted.

More importantly, I'm sorry to say that this additional text makes no
sense to me.  It just repeats what the doc string says (which also
makes no sense).  You cannot talk about using this function "to set
the value at KEY", without some explaining, because 'alist-get'
doesn't itself set anything, it _gets_ a value of KEY.  Right?

I believe this text needs a much longer and more detailed explanation,
and most probably also an example, to make sense.  (The doc string
could use some more explanations as well.)

Thanks.