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

Previous Next

Full log

Message #8 received at 23548 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Tino Calancha <f92capac <at> gmail.com>
Cc: 23548 <at> debbugs.gnu.org
Subject: Re: 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 <f92capac <at> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.