From: Stefan Kangas <stefan@marxist.se>
Date: Sat, 23 Oct 2021 17:20:31 +0000 (+0200)
Subject: Improve documentation of cl-reduce
X-Git-Tag: emacs-28.0.90~199
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=43914ab01f;p=emacs.git

Improve documentation of cl-reduce

* doc/misc/cl.texi (Mapping over Sequences): Change the
explanation of 'cl-reduce' so you don't need to have a major in
mathematics to understand it.  (Bug#24014)
---

diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi
index a6c3c32c0eb..0ec02495d5e 100644
--- a/doc/misc/cl.texi
+++ b/doc/misc/cl.texi
@@ -3364,9 +3364,13 @@ true for all elements.
 @end defun
 
 @defun cl-reduce function seq @t{&key :from-end :start :end :initial-value :key}
-This function combines the elements of @var{seq} using an associative
-binary operation.  Suppose @var{function} is @code{*} and @var{seq} is
-the list @code{(2 3 4 5)}.  The first two elements of the list are
+This function returns the result of calling @var{function} on the
+first and second element of @var{seq}, then calling @var{function}
+with that result and the third element of @var{seq}, then with that
+result and the third element of @var{seq}, etc.
+
+Here is an example.  Suppose @var{function} is @code{*} and @var{seq}
+is the list @code{(2 3 4 5)}.  The first two elements of the list are
 combined with @code{(* 2 3) = 6}; this is combined with the next
 element, @code{(* 6 4) = 24}, and that is combined with the final
 element: @code{(* 24 5) = 120}.  Note that the @code{*} function happens