From: Eli Zaretskii <eliz@gnu.org>
Date: Wed, 18 Aug 2021 19:07:30 +0000 (+0300)
Subject: Improve documentation of 'assoc'
X-Git-Tag: emacs-28.0.90~1446
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=78b427648b85d0f7e93ad5f18537ad9f2da055cb;p=emacs.git

Improve documentation of 'assoc'

* doc/lispref/lists.texi (Association Lists):
* src/fns.c (Fassoc): Document how TESTFN is called.  (Bug#50110)
---

diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index ac99835f7b3..bbe1dce42d8 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -1557,10 +1557,12 @@ of property lists and association lists.
 @defun assoc key alist &optional testfn
 This function returns the first association for @var{key} in
 @var{alist}, comparing @var{key} against the alist elements using
-@var{testfn} if it is non-@code{nil} and @code{equal} otherwise
-(@pxref{Equality Predicates}).  It returns @code{nil} if no
-association in @var{alist} has a @sc{car} equal to @var{key}.  For
-example:
+@var{testfn} if it is a function, and @code{equal} otherwise
+(@pxref{Equality Predicates}).  If @var{testfn} is a function, it is
+called with two arguments: the @sc{car} of an element from @var{alist}
+and @var{key}.  The function returns @code{nil} if no
+association in @var{alist} has a @sc{car} equal to @var{key}, as
+tested by @var{testfn}.  For example:
 
 @smallexample
 (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
diff --git a/src/fns.c b/src/fns.c
index 932800a3a49..5126439fd66 100644
--- a/src/fns.c
+++ b/src/fns.c
@@ -1755,7 +1755,8 @@ DEFUN ("assoc", Fassoc, Sassoc, 2, 3, 0,
        doc: /* Return non-nil if KEY is equal to the car of an element of ALIST.
 The value is actually the first element of ALIST whose car equals KEY.
 
-Equality is defined by TESTFN if non-nil or by `equal' if nil.  */)
+Equality is defined by the function TESTFN, defaulting to `equal'.
+TESTFN is called with 2 arguments: a car of an alist element and KEY.  */)
      (Lisp_Object key, Lisp_Object alist, Lisp_Object testfn)
 {
   if (eq_comparable_value (key) && NILP (testfn))