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

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

[debbugs-tracker] bug#34708: closed (alist-get has unclear documentation


From: GNU bug Tracking System
Subject: [debbugs-tracker] bug#34708: closed (alist-get has unclear documentation)
Date: Fri, 19 Apr 2019 01:34:02 +0000

Your message dated Fri, 19 Apr 2019 03:33:03 +0200
with message-id <address@hidden>
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
address@hidden)


-- 
34708: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=34708
GNU Bug Tracking System
Contact address@hidden with problems
--- Begin Message --- 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
address@hidden



--- End Message ---
--- Begin Message --- Subject: Re: bug#34708: alist-get has unclear documentation Date: Fri, 19 Apr 2019 03:33:03 +0200 User-agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux)
> 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.


--- End Message ---

reply via email to

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