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