From 1e3bbc57cc45d71728ddf2cfbe4e55289c991d31 Mon Sep 17 00:00:00 2001
From: Alex McLean <alex@slab.org>
Date: Sun, 29 Dec 2024 12:16:08 +0000
Subject: [PATCH] Documentation for all/each, and bugfix for each (#1233)

* bugfix for each(), and documentation for each() and all()
* had to hide each/all examples from tests
---
 packages/core/repl.mjs                        | 26 ++++++++++++++++++-
 .../src/repl/components/panel/Reference.jsx   |  4 +--
 2 files changed, 27 insertions(+), 3 deletions(-)

diff --git a/packages/core/repl.mjs b/packages/core/repl.mjs
index 7d3215a99..e703909ff 100644
--- a/packages/core/repl.mjs
+++ b/packages/core/repl.mjs
@@ -86,10 +86,33 @@ export function repl({
   const toggle = () => scheduler.toggle();
   const setCps = (cps) => scheduler.setCps(cps);
   const setCpm = (cpm) => scheduler.setCps(cpm / 60);
+
+  // TODO - not documented as jsdoc examples as the test framework doesn't simulate enough context for `each` and `all`..
+
+  /** Applies a function to all the running patterns. Note that the patterns are groups together into a single `stack` before the function is applied. This is probably what you want, but see `each` for
+   * a version that applies the function to each pattern separately.
+   * ```
+   * $: sound("bd - cp sd")
+   * $: sound("hh*8")
+   * all(fast("<2 3>"))
+   * ```
+   * ```
+   * $: sound("bd - cp sd")
+   * $: sound("hh*8")
+   * all(x => x.pianoroll())
+   * ```
+   */
   const all = function (transform) {
     allTransform = transform;
     return silence;
   };
+  /** Applies a function to each of the running patterns separately. This is intended for future use with upcoming 'stepwise' features. See `all` for a version that applies the function to all the patterns stacked together into a single pattern.
+   * ```
+   * $: sound("bd - cp sd")
+   * $: sound("hh*8")
+   * each(fast("<2 3>"))
+   * ```
+   */
   const each = function (transform) {
     eachTransform = transform;
     return silence;
@@ -161,7 +184,8 @@ export function repl({
       if (Object.keys(pPatterns).length) {
         let patterns = Object.values(pPatterns);
         if (eachTransform) {
-          patterns = patterns.map(eachTransform);
+          // Explicit lambda so only element (not index and array) are passed
+          patterns = patterns.map((x) => eachTransform(x));
         }
         pattern = stack(...patterns);
       } else if (eachTransform) {
diff --git a/website/src/repl/components/panel/Reference.jsx b/website/src/repl/components/panel/Reference.jsx
index 078208071..fbbf0a08c 100644
--- a/website/src/repl/components/panel/Reference.jsx
+++ b/website/src/repl/components/panel/Reference.jsx
@@ -58,8 +58,8 @@ export function Reference() {
         <div className="prose dark:prose-invert min-w-full px-1 ">
           <h2>API Reference</h2>
           <p>
-            This is the long list functions you can use! Remember that you don't need to remember all of those and that
-            you can already make music with a small set of functions!
+            This is the long list of functions you can use. Remember that you don't need to remember all of those and
+            that you can already make music with a small set of functions!
           </p>
           {visibleFunctions.map((entry, i) => (
             <section key={i}>