bug#57273: Improve `cl-reduce` docstring

bug#57273: Improve `cl-reduce` docstring

[Colin Woodbury]

[-- Attachment #1: Type: text/plain, Size: 388 bytes --]

This patch expands the docstring of `cl-reduce` to mention that the 
order of arguments to the given lambda is flipped when `:from-end` is 
used. This behaviour matches "right folds" in other languages, but this 
fact is otherwise hidden until the user's code suddenly breaks. The 
order flip is technically mentioned in the cl-lib manual, but in a 
somewhat cryptic way.

Cheers,

Colin

[-- Attachment #2: 0001-lisp-emacs-lisp-cl-seq.el-cl-reduce-Document-arg-ord.patch --]
[-- Type: text/x-patch, Size: 1058 bytes --]

From c2e8d04545664ca6ed6363a804d9607588f4df61 Mon Sep 17 00:00:00 2001
From: Colin Woodbury <colin@fosskers.ca>
Date: Thu, 18 Aug 2022 18:49:59 +0900
Subject: [PATCH] ; * lisp/emacs-lisp/cl-seq.el (cl-reduce): Document arg order
 flip when :from-end is used.

---
 lisp/emacs-lisp/cl-seq.el | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/lisp/emacs-lisp/cl-seq.el b/lisp/emacs-lisp/cl-seq.el
index 64ae05bf2a..60e204eaf5 100644
--- a/lisp/emacs-lisp/cl-seq.el
+++ b/lisp/emacs-lisp/cl-seq.el
@@ -139,6 +139,10 @@ only case where FUNCTION is called with fewer than two arguments.
 If SEQ contains exactly one element and no :INITIAL-VALUE is
 specified, then return that element and FUNCTION is not called.
 
+If :FROM-END is non-nil, the reduction occurs from the back of
+the SEQ moving forward, and the order of arguments to the
+FUNCTION is also reversed.
+
 \n(fn FUNCTION SEQ [KEYWORD VALUE]...)"
   (cl--parsing-keywords (:from-end (:start 0) :end :initial-value :key) ()
     (or (listp cl-seq) (setq cl-seq (append cl-seq nil)))
-- 
2.37.2

bug#57273: Improve `cl-reduce` docstring

[Lars Ingebrigtsen]

Colin Woodbury <colin@fosskers.ca> writes:

> This patch expands the docstring of `cl-reduce` to mention that the
> order of arguments to the given lambda is flipped when `:from-end` is
> used.

Thanks; pushed to the Emacs release branch.