Subject: bug#34708: closed (Re: bug#34708: alist-get has unclear documentation)

From: [email-masked] (GNU bug Tracking System)
Date: Fri, 19 Apr 2019 01:34:02 +0000

Your bug report

#34708: alist-get has unclear documentation

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
34708: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=34708
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#34708: alist-get has unclear documentation
From: Michael Heerdegen <[email-masked]>
To: Eric Abrahamsen <[email-masked]>
Cc: [email-masked]
Date: Fri, 19 Apr 2019 03:33:03 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

> Patch installed (master).  Can we close this report?
>
> I left the manual section about alist-get as is.  It is not perfect, but
> what I really would like to have instead in the long run is a chapter
> about map.el functions.  This is not subject of this report, however,
> and I'm not sure if map.el is mature enough to do that now.

Ok, closing.  Thanks everyone for the discussion.

Michael.

Subject: alist-get has unclear documentation
From: "Miguel V. S. Frasson" <[email-masked]>
To: [email-masked]
Date: Sat, 2 Mar 2019 01:50:10 -0300
List-Id: <debbugs-submit.debbugs.gnu.org>

Hi

In most recent subr.el (git repository, lisp folder), this is the
definition of alist-get:

(defun alist-get (key alist &optional default remove testfn)
  "Return the value associated with KEY in ALIST.
If KEY is not found in ALIST, return DEFAULT.
Use TESTFN to lookup in the alist if non-nil.  Otherwise, use `assq'.

This is a generalized variable suitable for use with `setf'.
When using it to set a value, optional argument REMOVE non-nil
means to remove KEY from ALIST if the new value is `eql' to DEFAULT."
  (ignore remove) ;;Silence byte-compiler.
  (let ((x (if (not testfn)
               (assq key alist)
             (assoc key alist testfn))))
    (if x (cdr x) default)))

* Last paragraph starts with `This'. What is `this'? ALIST? TESTFN?
alist-get itself? Since this doc-string is there for a long time, it
may be the case it makes sense and I didn't understand it, but again
in this case, others will not understand as well, unclear doc-string.

* How do I use `this' or `it' to set a value? Function is alist-*get*
but somehow I can set values. A simple example on doc-string and/or
info node would explain everything.

* Action of REMOVE is described, but it doesn't correspond to code.
REMOVE is ignored.

* Probably Elisp info follows misleading doc-string.

Miguel

-- 
Miguel Vinicius Santini Frasson
[email-masked]