GNU bug report logs - #34708
alist-get has unclear documentation

Previous Next

Full log

View this message in rfc822 format

From: help-debbugs <at> gnu.org (GNU bug Tracking System)
To: Michael Heerdegen <michael_heerdegen <at> web.de>
Cc: tracker <at> debbugs.gnu.org
Subject: bug#34708: closed (alist-get has unclear documentation)
Date: Fri, 19 Apr 2019 01:34:02 +0000

[Message part 1 (text/plain, inline)]

Your message dated Fri, 19 Apr 2019 03:33:03 +0200
with message-id <871s1y3hkg.fsf <at> web.de>
and subject line Re: bug#34708: alist-get has unclear documentation
has caused the debbugs.gnu.org bug report #34708,
regarding alist-get has unclear documentation
to be marked as done.

(If you believe you have received this mail in error, please contact
help-debbugs <at> gnu.org.)


-- 
34708: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=34708
GNU Bug Tracking System
Contact help-debbugs <at> gnu.org with problems

[Message part 2 (message/rfc822, inline)]

From: "Miguel V. S. Frasson" <mvsfrasson <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: alist-get has unclear documentation
Date: Sat, 2 Mar 2019 01:50:10 -0300

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
mvsfrasson <at> gmail.com

[Message part 3 (message/rfc822, inline)]

From: Michael Heerdegen <michael_heerdegen <at> web.de>
To: Eric Abrahamsen <eric <at> ericabrahamsen.net>
Cc: 34708-done <at> debbugs.gnu.org
Subject: Re: bug#34708: alist-get has unclear documentation
Date: Fri, 19 Apr 2019 03:33:03 +0200

> 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.

Previous Next

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