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

From: Tino Calancha <[email-masked]>
Date: Tue, 17 May 2016 02:07:21 +0900 (JST)

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

> 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).
For me either.  I was following the 'authority principle': someone 
wrote that doc. string because she thought is was clear enough.

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?
Right.  I miss they mention something like: using this function as
PLACE in `setf'.

> 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.)
I modified previous patch and added one example.  It may be an start for
getting it more comprehensible.

>From 78fa526404c6ea57e42c44423d1bfecef5b45eea Mon Sep 17 00:00:00 2001
From: Tino Calancha <[email-masked]>
Date: Tue, 17 May 2016 01:56:15 +0900
Subject: [PATCH] * lists.texi (alist-get): Document optional arg 'remove'

---
  doc/lispref/lists.texi | 23 ++++++++++++++++++-----
  1 file changed, 18 insertions(+), 5 deletions(-)

diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index c18c408..d9f3d17 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -1556,12 +1556,25 @@ Association Lists
  @end smallexample
  @end defun

-@defun alist-get key value &optional default
+@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.
+association for @var{key}, it returns the @sc{cdr}.
+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 in conjunction with @code{setf}
+to set the value of @var{alist} 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.
+
+For example:
+
+@smallexample
+(let ((myalist '((a . 1) (b . 2) (c . 3))))
+  (setf (alist-get 'a myalist 1 'remove) 1)
+  myalist)
+@result{} ((b . 2) (c . 3))
+@end smallexample
  @end defun

  @defun rassq value alist
-- 
2.8.1