docs(compose): update doc strings

thi-ng · Aug 28, 2023 · 1a69616 · 1a69616
1 parent ae0cf5b
commit 1a69616
Show file tree

Hide file tree

Showing 2 changed files with 38 additions and 20 deletions.
diff --git a/packages/compose/src/thread-first.ts b/packages/compose/src/thread-first.ts
@@ -1,29 +1,38 @@
 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
  * const neg = (x) => -x;
  * 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
@@ -1,29 +1,38 @@
 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
  * const neg = (x) => -x;
  * 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
  */