bug-gnu-emacs
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


From: Eli Zaretskii
Subject: bug#23548: 25.0.93; lists.texi (alist-get): Document optional arg 'remove'.
Date: Mon, 16 May 2016 19:20:06 +0300

> Date: Mon, 16 May 2016 23:13:35 +0900 (JST)
> From: Tino Calancha <address@hidden>
> 
> * 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.

> address@hidden 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 address@hidden and
> address@hidden is @code{eql} to @var{new-val}, then the entry at
> address@hidden 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.





reply via email to

[Prev in Thread] Current Thread [Next in Thread]