bug#34708: alist-get has unclear documentation

[Miguel V. S. Frasson]

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@gmail.com