path: root/guix/emacs-dash/emacs-dash-2.19.1-emacs-28.patch

From dc61f4641779616122692e34a32ba2a158ee034c Mon Sep 17 00:00:00 2001
From: "Basil L. Contovounesios" <contovob@tcd.ie>
Date: Mon, 11 Oct 2021 12:49:49 +0100
Subject: [PATCH] Fix overly wide docstrings

* dash.el (-map-when, -map-first, -map-last, -only-some?)
(-update-at, -split-with, -separate)
(dash--partition-all-in-steps-reversed, -partition-all-in-steps)
(-partition-in-steps, --zip-with, -union, -intersection, -prodfn):
Refill and reword docstrings to fit in 80 columns.
(-concat): Eta-reduce, defining as an alias of append.

* dev/examples.el (-partition-all-in-steps): Add a jagged test case.

* README.md:
* dash.texi: Regenerate docs.

Fixes #389.
---
 README.md       | 106 +++++++++++++++++++++++++++++++--------------
 dash.el         | 113 ++++++++++++++++++++++++++++++++----------------
 dash.texi       | 104 +++++++++++++++++++++++++++++++-------------
 dev/examples.el |   4 ++
 4 files changed, 227 insertions(+), 100 deletions(-)

diff --git a/README.md b/README.md
index 08126c3..076bd51 100644
--- a/README.md
+++ b/README.md
@@ -165,7 +165,7 @@ Functions returning a sublist of the original list.
 Functions returning a modified copy of the input list.
 
 * [`-keep`](#-keep-fn-list) `(fn list)`
-* [`-concat`](#-concat-rest-lists) `(&rest lists)`
+* [`-concat`](#-concat-rest-sequences) `(&rest sequences)`
 * [`-flatten`](#-flatten-l) `(l)`
 * [`-flatten-n`](#-flatten-n-num-list) `(num list)`
 * [`-replace`](#-replace-old-new-list) `(old new list)`
@@ -406,9 +406,9 @@ This function's anaphoric counterpart is `--map`.
 
 #### -map-when `(pred rep list)`
 
-Return a new list where the elements in `list` that do not match the `pred` function
-are unchanged, and where the elements in `list` that do match the `pred` function are mapped
-through the `rep` function.
+Use `pred` to conditionally apply `rep` to each item in `list`.
+Return a copy of `list` where the items for which `pred` returns nil
+are unchanged, and the rest are mapped through the `rep` function.
 
 Alias: `-replace-where`
 
@@ -422,7 +422,9 @@ See also: [`-update-at`](#-update-at-n-func-list)
 
 #### -map-first `(pred rep list)`
 
-Replace first item in `list` satisfying `pred` with result of `rep` called on this item.
+Use `pred` to determine the first item in `list` to call `rep` on.
+Return a copy of `list` where the first item for which `pred` returns
+non-nil is replaced with the result of calling `rep` on that item.
 
 See also: [`-map-when`](#-map-when-pred-rep-list), [`-replace-first`](#-replace-first-old-new-list)
 
@@ -434,7 +436,9 @@ See also: [`-map-when`](#-map-when-pred-rep-list), [`-replace-first`](#-replace-
 
 #### -map-last `(pred rep list)`
 
-Replace last item in `list` satisfying `pred` with result of `rep` called on this item.
+Use `pred` to determine the last item in `list` to call `rep` on.
+Return a copy of `list` where the last item for which `pred` returns
+non-nil is replaced with the result of calling `rep` on that item.
 
 See also: [`-map-when`](#-map-when-pred-rep-list), [`-replace-last`](#-replace-last-old-new-list)
 
@@ -784,9 +788,12 @@ Its anaphoric counterpart is `--keep`.
 (--keep (and (> it 3) (* 10 it)) '(1 2 3 4 5 6)) ;; => (40 50 60)
 ```
 
-#### -concat `(&rest lists)`
+#### -concat `(&rest sequences)`
 
-Return a new list with the concatenation of the elements in the supplied `lists`.
+Concatenate all the arguments and make the result a list.
+The result is a list whose elements are the elements of all the arguments.
+Each argument may be a list, vector or string.
+The last argument is not copied, just used as the tail of the new list.
 
 ```el
 (-concat '(1)) ;; => (1)
@@ -893,7 +900,9 @@ See also: [`-replace`](#-replace-old-new-list)
 
 #### -update-at `(n func list)`
 
-Return a list with element at `n`th position in `list` replaced with `(func (nth n list))`.
+Use `func` to update the `n`th element of `list`.
+Return a copy of `list` where the `n`th element is replaced with the
+result of calling `func` on it.
 
 See also: [`-map-when`](#-map-when-pred-rep-list)
 
@@ -1348,8 +1357,10 @@ Alias: `-none-p`
 
 #### -only-some? `(pred list)`
 
-Return `t` if at least one item of `list` matches `pred` and at least one item of `list` does not match `pred`.
-Return `nil` both if all items match the predicate or if none of the items match the predicate.
+Return t if different `list` items both satisfy and do not satisfy `pred`.
+That is, if `pred` returns both nil for at least one item, and
+non-nil for at least one other item in `list`.  Return nil if all
+items satisfy the predicate or none of them do.
 
 Alias: `-only-some-p`
 
@@ -1460,7 +1471,14 @@ is done in a single list traversal.
 
 #### -split-with `(pred list)`
 
-Return a list of ((-take-while `pred` `list`) (-drop-while `pred` `list`)), in no more than one pass through the list.
+Split `list` into a prefix satisfying `pred`, and the rest.
+The first sublist is the prefix of `list` with successive elements
+satisfying `pred`, and the second sublist is the remaining elements
+that do not.  The result is like performing
+
+    ((-take-while `pred` `list`) (-drop-while `pred` `list`))
+
+but in no more than a single pass through `list`.
 
 ```el
 (-split-with 'even? '(1 2 3 4)) ;; => (nil (1 2 3 4))
@@ -1503,7 +1521,12 @@ This function can be thought of as a generalization of
 
 #### -separate `(pred list)`
 
-Return a list of ((-filter `pred` `list`) (-remove `pred` `list`)), in one pass through the list.
+Split `list` into two sublists based on whether items satisfy `pred`.
+The result is like performing
+
+    ((-filter `pred` `list`) (-remove `pred` `list`))
+
+but in a single pass through `list`.
 
 ```el
 (-separate (lambda (num) (= 0 (% num 2))) '(1 2 3 4 5 6 7)) ;; => ((2 4 6) (1 3 5 7))
@@ -1536,9 +1559,9 @@ The last group may contain less than `n` items.
 
 #### -partition-in-steps `(n step list)`
 
-Return a new list with the items in `list` grouped into `n`-sized sublists at offsets `step` apart.
-If there are not enough items to make the last group `n`-sized,
-those items are discarded.
+Partition `list` into sublists of length `n` that are `step` items apart.
+Like [`-partition-all-in-steps`](#-partition-all-in-steps-n-step-list), but if there are not enough items
+to make the last group `n`-sized, those items are discarded.
 
 ```el
 (-partition-in-steps 2 1 '(1 2 3 4)) ;; => ((1 2) (2 3) (3 4))
@@ -1548,8 +1571,9 @@ those items are discarded.
 
 #### -partition-all-in-steps `(n step list)`
 
-Return a new list with the items in `list` grouped into `n`-sized sublists at offsets `step` apart.
-The last groups may contain less than `n` items.
+Partition `list` into sublists of length `n` that are `step` items apart.
+Adjacent groups may overlap if `n` exceeds the `step` stride.
+Trailing groups may contain less than `n` items.
 
 ```el
 (-partition-all-in-steps 2 1 '(1 2 3 4)) ;; => ((1 2) (2 3) (3 4) (4))
@@ -1728,9 +1752,9 @@ Operations pretending lists are sets.
 
 #### -union `(list list2)`
 
-Return a new list containing the elements of `list` and elements of `list2` that are not in `list`.
-The test for equality is done with `equal`,
-or with `-compare-fn` if that's non-nil.
+Return a new list of all elements appearing in either `list1` or `list2`.
+Equality is defined by the value of `-compare-fn` if non-nil;
+otherwise `equal`.
 
 ```el
 (-union '(1 2 3) '(3 4 5)) ;; => (1 2 3 4 5)
@@ -1752,9 +1776,9 @@ or with `-compare-fn` if that's non-nil.
 
 #### -intersection `(list list2)`
 
-Return a new list containing only the elements that are members of both `list` and `list2`.
-The test for equality is done with `equal`,
-or with `-compare-fn` if that's non-nil.
+Return a new list of the elements appearing in both `list1` and `list2`.
+Equality is defined by the value of `-compare-fn` if non-nil;
+otherwise `equal`.
 
 ```el
 (-intersection () ()) ;; => ()
@@ -3075,18 +3099,36 @@ In types: (a -> a) -> a -> a.
 
 #### -prodfn `(&rest fns)`
 
-Take a list of n functions and return a function that takes a
-list of length n, applying i-th function to i-th element of the
-input list.  Returns a list of length n.
+Return a function that applies each of `fns` to each of a list of arguments.
+
+Takes a list of `n` functions and returns a function that takes a
+list of length `n`, applying `i`th function to `i`th element of the
+input list.  Returns a list of length `n`.
 
-In types (for n=2): ((a -> b), (c -> d)) -> (a, c) -> (b, d)
+In types (for `n`=2): ((a -> b), (c -> d)) -> (a, c) -> (b, d)
 
 This function satisfies the following laws:
 
-    (-compose (-prodfn f g ...) (-prodfn f' g' ...)) = (-prodfn (-compose f f') (-compose g g') ...)
-    (-prodfn f g ...) = (-juxt (-compose f (-partial 'nth 0)) (-compose g (-partial 'nth 1)) ...)
-    (-compose (-prodfn f g ...) (-juxt f' g' ...)) = (-juxt (-compose f f') (-compose g g') ...)
-    (-compose (-partial 'nth n) (-prod f1 f2 ...)) = (-compose fn (-partial 'nth n))
+      (-compose (-prodfn f g ...)
+                (-prodfn f' g' ...))
+    = (-prodfn (-compose f f')
+               (-compose g g')
+               ...)
+
+      (-prodfn f g ...)
+    = (-juxt (-compose f (-partial #'nth 0))
+             (-compose g (-partial #'nth 1))
+             ...)
+
+      (-compose (-prodfn f g ...)
+                (-juxt f' g' ...))
+    = (-juxt (-compose f f')
+             (-compose g g')
+             ...)
+
+      (-compose (-partial #'nth n)
+                (-prod f1 f2 ...))
+    = (-compose fn (-partial #'nth n))
 
 ```el
 (funcall (-prodfn '1+ '1- 'number-to-string) '(1 2 3)) ;; => (2 1 "3")
diff --git a/dash.el b/dash.el
index 6386c5f..472ffa5 100644
--- a/dash.el
+++ b/dash.el
@@ -613,9 +613,9 @@ For a side-effecting variant, see also `-each-indexed'."
        (nreverse ,r))))
 
 (defun -map-when (pred rep list)
-  "Return a new list where the elements in LIST that do not match the PRED function
-are unchanged, and where the elements in LIST that do match the PRED function are mapped
-through the REP function.
+  "Use PRED to conditionally apply REP to each item in LIST.
+Return a copy of LIST where the items for which PRED returns nil
+are unchanged, and the rest are mapped through the REP function.
 
 Alias: `-replace-where'
 
@@ -626,7 +626,9 @@ See also: `-update-at'"
 (defalias '--replace-where '--map-when)
 
 (defun -map-first (pred rep list)
-  "Replace first item in LIST satisfying PRED with result of REP called on this item.
+  "Use PRED to determine the first item in LIST to call REP on.
+Return a copy of LIST where the first item for which PRED returns
+non-nil is replaced with the result of calling REP on that item.
 
 See also: `-map-when', `-replace-first'"
   (let (front)
@@ -643,7 +645,9 @@ See also: `-map-when', `-replace-first'"
   `(-map-first (lambda (it) ,pred) (lambda (it) (ignore it) ,rep) ,list))
 
 (defun -map-last (pred rep list)
-  "Replace last item in LIST satisfying PRED with result of REP called on this item.
+  "Use PRED to determine the last item in LIST to call REP on.
+Return a copy of LIST where the last item for which PRED returns
+non-nil is replaced with the result of calling REP on that item.
 
 See also: `-map-when', `-replace-last'"
   (nreverse (-map-first pred rep (reverse list))))
@@ -739,10 +743,7 @@ See also: `-flatten'"
     (setq list (apply #'append (mapcar #'-list list))))
   list)
 
-(defun -concat (&rest lists)
-  "Return a new list with the concatenation of the elements in the supplied LISTS."
-  (declare (pure t) (side-effect-free t))
-  (apply 'append lists))
+(defalias '-concat #'append)
 
 (defalias '-copy 'copy-sequence
   "Create a shallow copy of LIST.
@@ -1057,8 +1058,10 @@ Alias: `-none-p'"
        (---truthy? (and ,y ,n)))))
 
 (defun -only-some? (pred list)
-  "Return `t` if at least one item of LIST matches PRED and at least one item of LIST does not match PRED.
-Return `nil` both if all items match the predicate or if none of the items match the predicate.
+  "Return t if different LIST items both satisfy and do not satisfy PRED.
+That is, if PRED returns both nil for at least one item, and
+non-nil for at least one other item in LIST.  Return nil if all
+items satisfy the predicate or none of them do.
 
 Alias: `-only-some-p'"
   (--only-some? (funcall pred it) list))
@@ -1217,11 +1220,15 @@ See also: `-replace'"
     (nconc (car split-list) (cons x (cdr (cadr split-list))))))
 
 (defun -update-at (n func list)
-  "Return a list with element at Nth position in LIST replaced with `(func (nth n list))`.
+  "Use FUNC to update the Nth element of LIST.
+Return a copy of LIST where the Nth element is replaced with the
+result of calling FUNC on it.
 
 See also: `-map-when'"
   (let ((split-list (-split-at n list)))
-    (nconc (car split-list) (cons (funcall func (car (cadr split-list))) (cdr (cadr split-list))))))
+    (nconc (car split-list)
+           (cons (funcall func (car (cadr split-list)))
+                 (cdr (cadr split-list))))))
 
 (defmacro --update-at (n form list)
   "Anaphoric version of `-update-at'."
@@ -1270,7 +1277,14 @@ See also: `-remove-at', `-remove'"
        (list (nreverse ,r) ,l))))
 
 (defun -split-with (pred list)
-  "Return a list of ((-take-while PRED LIST) (-drop-while PRED LIST)), in no more than one pass through the list."
+  "Split LIST into a prefix satisfying PRED, and the rest.
+The first sublist is the prefix of LIST with successive elements
+satisfying PRED, and the second sublist is the remaining elements
+that do not.  The result is like performing
+
+  ((-take-while PRED LIST) (-drop-while PRED LIST))
+
+but in no more than a single pass through LIST."
   (--split-with (funcall pred it) list))
 
 (defmacro -split-on (item list)
@@ -1318,11 +1332,16 @@ This function can be thought of as a generalization of
        (list (nreverse ,y) (nreverse ,n)))))
 
 (defun -separate (pred list)
-  "Return a list of ((-filter PRED LIST) (-remove PRED LIST)), in one pass through the list."
+  "Split LIST into two sublists based on whether items satisfy PRED.
+The result is like performing
+
+  ((-filter PRED LIST) (-remove PRED LIST))
+
+but in a single pass through LIST."
   (--separate (funcall pred it) list))
 
 (defun dash--partition-all-in-steps-reversed (n step list)
-  "Used by `-partition-all-in-steps' and `-partition-in-steps'."
+  "Like `-partition-all-in-steps', but the result is reversed."
   (when (< step 1)
     (signal 'wrong-type-argument
             `("Step size < 1 results in juicy infinite loops" ,step)))
@@ -1333,19 +1352,20 @@ This function can be thought of as a generalization of
     result))
 
 (defun -partition-all-in-steps (n step list)
-  "Return a new list with the items in LIST grouped into N-sized sublists at offsets STEP apart.
-The last groups may contain less than N items."
+  "Partition LIST into sublists of length N that are STEP items apart.
+Adjacent groups may overlap if N exceeds the STEP stride.
+Trailing groups may contain less than N items."
   (declare (pure t) (side-effect-free t))
   (nreverse (dash--partition-all-in-steps-reversed n step list)))
 
 (defun -partition-in-steps (n step list)
-  "Return a new list with the items in LIST grouped into N-sized sublists at offsets STEP apart.
-If there are not enough items to make the last group N-sized,
-those items are discarded."
+  "Partition LIST into sublists of length N that are STEP items apart.
+Like `-partition-all-in-steps', but if there are not enough items
+to make the last group N-sized, those items are discarded."
   (declare (pure t) (side-effect-free t))
   (let ((result (dash--partition-all-in-steps-reversed n step list)))
     (while (and result (< (length (car result)) n))
-      (!cdr result))
+      (pop result))
     (nreverse result)))
 
 (defun -partition-all (n list)
@@ -1523,7 +1543,8 @@ elements of LIST.  Keys are compared by `equal'."
 (defmacro --zip-with (form list1 list2)
   "Anaphoric form of `-zip-with'.
 
-The elements in list1 are bound as symbol `it', the elements in list2 as symbol `other'."
+Each element in turn of LIST1 is bound to `it', and of LIST2 to
+`other', before evaluating FORM."
   (declare (debug (form form form)))
   (let ((r (make-symbol "result"))
         (l1 (make-symbol "list1"))
@@ -2611,9 +2632,9 @@ Alias: `-uniq'"
 (defalias '-uniq '-distinct)
 
 (defun -union (list list2)
-  "Return a new list containing the elements of LIST and elements of LIST2 that are not in LIST.
-The test for equality is done with `equal',
-or with `-compare-fn' if that's non-nil."
+  "Return a new list of all elements appearing in either LIST1 or LIST2.
+Equality is defined by the value of `-compare-fn' if non-nil;
+otherwise `equal'."
   ;; We fall back to iteration implementation if the comparison
   ;; function isn't one of `eq', `eql' or `equal'.
   (let* ((result (reverse list))
@@ -2630,9 +2651,9 @@ or with `-compare-fn' if that's non-nil."
     (nreverse result)))
 
 (defun -intersection (list list2)
-  "Return a new list containing only the elements that are members of both LIST and LIST2.
-The test for equality is done with `equal',
-or with `-compare-fn' if that's non-nil."
+  "Return a new list of the elements appearing in both LIST1 and LIST2.
+Equality is defined by the value of `-compare-fn' if non-nil;
+otherwise `equal'."
   (--filter (-contains? list2 it) list))
 
 (defun -difference (list list2)
@@ -3316,18 +3337,36 @@ In types: (a -> a) -> a -> a."
           re)))))
 
 (defun -prodfn (&rest fns)
-  "Take a list of n functions and return a function that takes a
-list of length n, applying i-th function to i-th element of the
-input list.  Returns a list of length n.
+  "Return a function that applies each of FNS to each of a list of arguments.
+
+Takes a list of N functions and returns a function that takes a
+list of length N, applying Ith function to Ith element of the
+input list.  Returns a list of length N.
 
-In types (for n=2): ((a -> b), (c -> d)) -> (a, c) -> (b, d)
+In types (for N=2): ((a -> b), (c -> d)) -> (a, c) -> (b, d)
 
 This function satisfies the following laws:
 
-  (-compose (-prodfn f g ...) (-prodfn f\\=' g\\=' ...)) = (-prodfn (-compose f f\\=') (-compose g g\\=') ...)
-  (-prodfn f g ...) = (-juxt (-compose f (-partial \\='nth 0)) (-compose g (-partial \\='nth 1)) ...)
-  (-compose (-prodfn f g ...) (-juxt f\\=' g\\=' ...)) = (-juxt (-compose f f\\=') (-compose g g\\=') ...)
-  (-compose (-partial \\='nth n) (-prod f1 f2 ...)) = (-compose fn (-partial \\='nth n))"
+    (-compose (-prodfn f g ...)
+              (-prodfn f\\=' g\\=' ...))
+  = (-prodfn (-compose f f\\=')
+             (-compose g g\\=')
+             ...)
+
+    (-prodfn f g ...)
+  = (-juxt (-compose f (-partial #\\='nth 0))
+           (-compose g (-partial #\\='nth 1))
+           ...)
+
+    (-compose (-prodfn f g ...)
+              (-juxt f\\=' g\\=' ...))
+  = (-juxt (-compose f f\\=')
+           (-compose g g\\=')
+           ...)
+
+    (-compose (-partial #\\='nth n)
+              (-prod f1 f2 ...))
+  = (-compose fn (-partial #\\='nth n))"
   (lambda (x) (-zip-with 'funcall fns x)))
 
 ;;; Font lock
diff --git a/dash.texi b/dash.texi
index f235094..9bcff91 100644
--- a/dash.texi
+++ b/dash.texi
@@ -260,9 +260,9 @@ This function's anaphoric counterpart is @code{--map}.
 
 @anchor{-map-when}
 @defun -map-when (pred rep list)
-Return a new list where the elements in @var{list} that do not match the @var{pred} function
-are unchanged, and where the elements in @var{list} that do match the @var{pred} function are mapped
-through the @var{rep} function.
+Use @var{pred} to conditionally apply @var{rep} to each item in @var{list}.
+Return a copy of @var{list} where the items for which @var{pred} returns nil
+are unchanged, and the rest are mapped through the @var{rep} function.
 
 Alias: @code{-replace-where}
 
@@ -286,7 +286,9 @@ See also: @code{-update-at} (@pxref{-update-at})
 
 @anchor{-map-first}
 @defun -map-first (pred rep list)
-Replace first item in @var{list} satisfying @var{pred} with result of @var{rep} called on this item.
+Use @var{pred} to determine the first item in @var{list} to call @var{rep} on.
+Return a copy of @var{list} where the first item for which @var{pred} returns
+non-nil is replaced with the result of calling @var{rep} on that item.
 
 See also: @code{-map-when} (@pxref{-map-when}), @code{-replace-first} (@pxref{-replace-first})
 
@@ -308,7 +310,9 @@ See also: @code{-map-when} (@pxref{-map-when}), @code{-replace-first} (@pxref{-r
 
 @anchor{-map-last}
 @defun -map-last (pred rep list)
-Replace last item in @var{list} satisfying @var{pred} with result of @var{rep} called on this item.
+Use @var{pred} to determine the last item in @var{list} to call @var{rep} on.
+Return a copy of @var{list} where the last item for which @var{pred} returns
+non-nil is replaced with the result of calling @var{rep} on that item.
 
 See also: @code{-map-when} (@pxref{-map-when}), @code{-replace-last} (@pxref{-replace-last})
 
@@ -892,8 +896,11 @@ Its anaphoric counterpart is @code{--keep}.
 @end defun
 
 @anchor{-concat}
-@defun -concat (&rest lists)
-Return a new list with the concatenation of the elements in the supplied @var{lists}.
+@defun -concat (&rest sequences)
+Concatenate all the arguments and make the result a list.
+The result is a list whose elements are the elements of all the arguments.
+Each argument may be a list, vector or string.
+The last argument is not copied, just used as the tail of the new list.
 
 @example
 @group
@@ -1077,7 +1084,9 @@ See also: @code{-replace} (@pxref{-replace})
 
 @anchor{-update-at}
 @defun -update-at (n func list)
-Return a list with element at Nth position in @var{list} replaced with `(func (nth n list))`.
+Use @var{func} to update the Nth element of @var{list}.
+Return a copy of @var{list} where the Nth element is replaced with the
+result of calling @var{func} on it.
 
 See also: @code{-map-when} (@pxref{-map-when})
 
@@ -1842,8 +1851,10 @@ Alias: @code{-none-p}
 
 @anchor{-only-some?}
 @defun -only-some? (pred list)
-Return `t` if at least one item of @var{list} matches @var{pred} and at least one item of @var{list} does not match @var{pred}.
-Return `nil` both if all items match the predicate or if none of the items match the predicate.
+Return t if different @var{list} items both satisfy and do not satisfy @var{pred}.
+That is, if @var{pred} returns both nil for at least one item, and
+non-nil for at least one other item in @var{list}.  Return nil if all
+items satisfy the predicate or none of them do.
 
 Alias: @code{-only-some-p}
 
@@ -2035,7 +2046,14 @@ is done in a single list traversal.
 
 @anchor{-split-with}
 @defun -split-with (pred list)
-Return a list of ((-take-while @var{pred} @var{list}) (-drop-while @var{pred} @var{list})), in no more than one pass through the list.
+Split @var{list} into a prefix satisfying @var{pred}, and the rest.
+The first sublist is the prefix of @var{list} with successive elements
+satisfying @var{pred}, and the second sublist is the remaining elements
+that do not.  The result is like performing
+
+  ((-take-while @var{pred} @var{list}) (-drop-while @var{pred} @var{list}))
+
+but in no more than a single pass through @var{list}.
 
 @example
 @group
@@ -2108,7 +2126,12 @@ This function can be thought of as a generalization of
 
 @anchor{-separate}
 @defun -separate (pred list)
-Return a list of ((-filter @var{pred} @var{list}) (-remove @var{pred} @var{list})), in one pass through the list.
+Split @var{list} into two sublists based on whether items satisfy @var{pred}.
+The result is like performing
+
+  ((-filter @var{pred} @var{list}) (-remove @var{pred} @var{list}))
+
+but in a single pass through @var{list}.
 
 @example
 @group
@@ -2171,9 +2194,9 @@ The last group may contain less than @var{n} items.
 
 @anchor{-partition-in-steps}
 @defun -partition-in-steps (n step list)
-Return a new list with the items in @var{list} grouped into @var{n}-sized sublists at offsets @var{step} apart.
-If there are not enough items to make the last group @var{n}-sized,
-those items are discarded.
+Partition @var{list} into sublists of length @var{n} that are @var{step} items apart.
+Like @code{-partition-all-in-steps} (@pxref{-partition-all-in-steps}), but if there are not enough items
+to make the last group @var{n}-sized, those items are discarded.
 
 @example
 @group
@@ -2193,8 +2216,9 @@ those items are discarded.
 
 @anchor{-partition-all-in-steps}
 @defun -partition-all-in-steps (n step list)
-Return a new list with the items in @var{list} grouped into @var{n}-sized sublists at offsets @var{step} apart.
-The last groups may contain less than @var{n} items.
+Partition @var{list} into sublists of length @var{n} that are @var{step} items apart.
+Adjacent groups may overlap if @var{n} exceeds the @var{step} stride.
+Trailing groups may contain less than @var{n} items.
 
 @example
 @group
@@ -2519,9 +2543,9 @@ Operations pretending lists are sets.
 
 @anchor{-union}
 @defun -union (list list2)
-Return a new list containing the elements of @var{list} and elements of @var{list2} that are not in @var{list}.
-The test for equality is done with @code{equal},
-or with @code{-compare-fn} if that's non-nil.
+Return a new list of all elements appearing in either @var{list1} or @var{list2}.
+Equality is defined by the value of @code{-compare-fn} if non-nil;
+otherwise @code{equal}.
 
 @example
 @group
@@ -2563,9 +2587,9 @@ or with @code{-compare-fn} if that's non-nil.
 
 @anchor{-intersection}
 @defun -intersection (list list2)
-Return a new list containing only the elements that are members of both @var{list} and @var{list2}.
-The test for equality is done with @code{equal},
-or with @code{-compare-fn} if that's non-nil.
+Return a new list of the elements appearing in both @var{list1} and @var{list2}.
+Equality is defined by the value of @code{-compare-fn} if non-nil;
+otherwise @code{equal}.
 
 @example
 @group
@@ -4638,18 +4662,36 @@ In types: (a -> a) -> a -> a.
 
 @anchor{-prodfn}
 @defun -prodfn (&rest fns)
-Take a list of n functions and return a function that takes a
-list of length n, applying i-th function to i-th element of the
-input list.  Returns a list of length n.
+Return a function that applies each of @var{fns} to each of a list of arguments.
+
+Takes a list of @var{n} functions and returns a function that takes a
+list of length @var{n}, applying Ith function to Ith element of the
+input list.  Returns a list of length @var{n}.
 
-In types (for n=2): ((a -> b), (c -> d)) -> (a, c) -> (b, d)
+In types (for @var{n}=2): ((a -> b), (c -> d)) -> (a, c) -> (b, d)
 
 This function satisfies the following laws:
 
-  (-compose (-prodfn f g @dots{}) (-prodfn f' g' @dots{})) = (-prodfn (-compose f f') (-compose g g') @dots{})
-  (-prodfn f g @dots{}) = (-juxt (-compose f (-partial 'nth 0)) (-compose g (-partial 'nth 1)) @dots{})
-  (-compose (-prodfn f g @dots{}) (-juxt f' g' @dots{})) = (-juxt (-compose f f') (-compose g g') @dots{})
-  (-compose (-partial 'nth n) (-prod f1 f2 @dots{})) = (-compose fn (-partial 'nth n))
+    (-compose (-prodfn f g @dots{})
+              (-prodfn f' g' @dots{}))
+  = (-prodfn (-compose f f')
+             (-compose g g')
+             @dots{})
+
+    (-prodfn f g @dots{})
+  = (-juxt (-compose f (-partial #'nth 0))
+           (-compose g (-partial #'nth 1))
+           @dots{})
+
+    (-compose (-prodfn f g @dots{})
+              (-juxt f' g' @dots{}))
+  = (-juxt (-compose f f')
+           (-compose g g')
+           @dots{})
+
+    (-compose (-partial #'nth n)
+              (-prod f1 f2 @dots{}))
+  = (-compose fn (-partial #'nth n))
 
 @example
 @group
diff --git a/dev/examples.el b/dev/examples.el
index 480304e..fccda8b 100644
--- a/dev/examples.el
+++ b/dev/examples.el
@@ -852,6 +852,10 @@ value rather than consuming a list to produce a single value."
     (-partition-all-in-steps 2 1 '(1 2 3 4)) => '((1 2) (2 3) (3 4) (4))
     (-partition-all-in-steps 3 2 '(1 2 3 4)) => '((1 2 3) (3 4))
     (-partition-all-in-steps 3 2 '(1 2 3 4 5)) => '((1 2 3) (3 4 5) (5))
+    (-partition-all-in-steps 4 2 '(0 1 2 3 4 5 6)) => '((0 1 2 3)
+                                                        (2 3 4 5)
+                                                        (4 5 6)
+                                                        (6))
     (-partition-all-in-steps 2 1 '(1)) => '((1))
     (-partition-all-in-steps 2 0 '(1)) !!> wrong-type-argument
     (-partition-all-in-steps 2 -1 '(1)) !!> wrong-type-argument)