From 1a6961632244a70b9d0262edbacee269795bdf28 Mon Sep 17 00:00:00 2001
From: Karsten Schmidt <k@thi.ng>
Date: Mon, 28 Aug 2023 22:05:30 +0200
Subject: [PATCH] docs(compose): update doc strings

---
 packages/compose/src/thread-first.ts | 29 ++++++++++++++++++----------
 packages/compose/src/thread-last.ts  | 29 ++++++++++++++++++----------
 2 files changed, 38 insertions(+), 20 deletions(-)

diff --git a/packages/compose/src/thread-first.ts b/packages/compose/src/thread-first.ts
index 006702f0f9..7597d227be 100644
--- a/packages/compose/src/thread-first.ts
+++ b/packages/compose/src/thread-first.ts
@@ -1,10 +1,16 @@
 import type { FnAny } from "@thi.ng/api";
 
 /**
- * Takes an `init` value and a number of functions and/or function
- * tuples, consisting of: `[fn, ...args]`. Executes each function
- * (or tuple) with the return value of the previous expression inserted
- * as first argument, using `init` for the first expression.
+ * Similar to {@link threadLast}. A dataflow operator to improve the legibility
+ * of long (or deeply nested) call expressions. Takes an `init` value and a
+ * number of functions and/or function tuples, consisting of: `[fn, ...args]`.
+ * Executes each function (or tuple) with the return value of the previous
+ * step/function inserted as **first** argument, using `init` as the first
+ * expression. Returns result of last function/step given.
+ *
+ * @remarks
+ * This operator allows the code to be read more easily in the order of
+ * execution (same as the `->` operator/macro in Clojure).
  *
  * @example
  * ```ts
@@ -12,18 +18,21 @@ import type { FnAny } from "@thi.ng/api";
  * const sub = (a, b) => a - b;
  * const div = (a, b) => a / b;
  *
+ * // without operator: (-5 - 10) / 20
+ * console.log(div(sub(neg(5), 10), 20));
+ * // -0.75
+ *
+ * // rewritten using operator:
  * threadFirst(
  *   5,
  *   neg,       // -5
- *   [sub, 20], // -5 - 20 = -25
- *   [div, 10]  // -25 / 10 = -2.5
+ *   [sub, 10], // (-5) - 10
+ *   [div, 20], // (-5 - 10) / 20
+ *   console.log
  * );
- *
- * // -2.5
+ * // -0.75
  * ```
  *
- * {@link threadLast}
- *
  * @param init - start value
  * @param fns - functions / S-expressions
  */
diff --git a/packages/compose/src/thread-last.ts b/packages/compose/src/thread-last.ts
index 7c7a997f3b..f706465935 100644
--- a/packages/compose/src/thread-last.ts
+++ b/packages/compose/src/thread-last.ts
@@ -1,10 +1,16 @@
 import type { FnAny } from "@thi.ng/api";
 
 /**
- * Takes an `init` value and a number of functions and/or function
- * tuples, consisting of: `[fn, ...args]`. Executes each function
- * (or tuple) with the return value of the previous expression inserted
- * as last argument, using `init` for the first expression.
+ * Similar to {@link threadFirst}. A dataflow operator to improve the legibility
+ * of long (or deeply nested) call expressions. Takes an `init` value and a
+ * number of functions and/or function tuples, consisting of: `[fn, ...args]`.
+ * Executes each function (or tuple) with the return value of the previous
+ * step/function inserted as **last** argument, using `init` as the first
+ * expression. Returns result of last function/step given.
+ *
+ * @remarks
+ * This operator allows the code to be read more easily in the order of
+ * execution (same as the `->>` operator/macro in Clojure).
  *
  * @example
  * ```ts
@@ -12,18 +18,21 @@ import type { FnAny } from "@thi.ng/api";
  * const sub = (a, b) => a - b;
  * const div = (a, b) => a / b;
  *
+ * // without operator: 20 / (10 - (-5))
+ * console.log(div(20, sub(10, neg(5))));
+ * // 1.3333333333333333
+ *
+ * // rewritten using operator:
  * threadLast(
  *   5,
  *   neg,       // -5
- *   [sub, 10], // 20 - (-5) = 25
- *   [div, 10]  // 10 / 25 = 0.4
+ *   [sub, 10], // 10 - (-5)
+ *   [div, 20],  // 20 / (10 - (-5))
+ *   console.log
  * );
- *
- * // 0.4
+ * // 1.3333333333333333
  * ```
  *
- * {@link threadFirst}
- *
  * @param init - start value
  * @param fns - functions / S-expressions
  */