From 78b427648b85d0f7e93ad5f18537ad9f2da055cb Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Wed, 18 Aug 2021 22:07:30 +0300 Subject: [PATCH] Improve documentation of 'assoc' * doc/lispref/lists.texi (Association Lists): * src/fns.c (Fassoc): Document how TESTFN is called. (Bug#50110) --- doc/lispref/lists.texi | 10 ++++++---- src/fns.c | 3 ++- 2 files changed, 8 insertions(+), 5 deletions(-) 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)) -- 2.39.2