From 69211b870164d0eaf3ea55358bbf9cafec5e6e39 Mon Sep 17 00:00:00 2001
From: Alexandre Gravel-Raymond <agravelraymond@deezer.com>
Date: Sun, 24 Mar 2024 12:22:26 +0100
Subject: [PATCH] Document signals

---
 packages/core/signal.mjs            | 56 +++++++++++++++++++++++++++++
 website/src/pages/learn/signals.mdx | 32 ++++++++++++++---
 2 files changed, 84 insertions(+), 4 deletions(-)

diff --git a/packages/core/signal.mjs b/packages/core/signal.mjs
index c37ef400..546665be 100644
--- a/packages/core/signal.mjs
+++ b/packages/core/signal.mjs
@@ -143,7 +143,24 @@ export const rand = signal(timeToRand);
 export const rand2 = rand.toBipolar();
 
 export const _brandBy = (p) => rand.fmap((x) => x < p);
+
+/**
+ * A continuous pattern of 0 or 1 (binary random), with a probability for the value being 1
+ * 
+ * @name brandBy
+ * @param {number} probability - a number between 0 and 1
+ * @example
+ * s("hh*10").pan(brandBy(0.2))
+ */
 export const brandBy = (pPat) => reify(pPat).fmap(_brandBy).innerJoin();
+
+/**
+ * A continuous pattern of 0 or 1 (binary random)
+ * 
+ * @name brand
+ * @example
+ * s("hh*10").pan(brand)
+ */
 export const brand = _brandBy(0.5);
 
 export const _irand = (i) => rand.fmap((x) => Math.trunc(x * i));
@@ -397,6 +414,8 @@ export const chooseInWith = (pat, xs) => {
  * Chooses randomly from the given list of elements.
  * @param  {...any} xs values / patterns to choose from.
  * @returns {Pattern} - a continuous pattern.
+ * @example
+ * note("c2 g2!2 d2 f1").s(choose("sine", "triangle", "bd:6"))
  */
 export const choose = (...xs) => chooseWith(rand, xs);
 
@@ -423,6 +442,7 @@ Pattern.prototype.choose2 = function (...xs) {
 
 /**
  * Picks one of the elements at random each cycle.
+ * @synonyms randcat
  * @returns {Pattern}
  * @example
  * chooseCycles("bd", "hh", "sd").s().fast(8)
@@ -451,10 +471,26 @@ const _wchooseWith = function (pat, ...pairs) {
 
 const wchooseWith = (...args) => _wchooseWith(...args).outerJoin();
 
+/**
+ * Chooses randomly from the given list of elements by giving a probability to each element
+ * @param {...any} pairs arrays of value and weight
+ * @returns {Pattern} - a continuous pattern.
+ * @example
+ * note("c2 g2!2 d2 f1").s(wchoose(["sine",10], ["triangle",1], ["bd:6",1]))
+ */
 export const wchoose = (...pairs) => wchooseWith(rand, ...pairs);
 
+/**
+ * Picks one of the elements at random each cycle by giving a probability to each element
+ * @synonyms wrandcat
+ * @returns {Pattern}
+ * @example
+ * wchooseCycles(["bd",10], ["hh",1], ["sd",1]).s().fast(8)
+ */
 export const wchooseCycles = (...pairs) => _wchooseWith(rand, ...pairs).innerJoin();
 
+export const wrandcat = wchooseCycles;
+
 // this function expects pat to be a pattern of floats...
 export const perlinWith = (pat) => {
   const pata = pat.fmap(Math.floor);
@@ -523,6 +559,11 @@ export const degrade = register('degrade', (pat) => pat._degradeBy(0.5));
  * @returns Pattern
  * @example
  * s("hh*8").undegradeBy(0.2)
+ * @example
+ * s("hh*10").layer(
+ *   x => x.degradeBy(0.2).pan(0),
+ *   x => x.undegradeBy(0.8).pan(1)
+ * )
  */
 export const undegradeBy = register('undegradeBy', function (x, pat) {
   return pat._degradeByWith(
@@ -531,6 +572,21 @@ export const undegradeBy = register('undegradeBy', function (x, pat) {
   );
 });
 
+/**
+ * Inverse of `degrade`: Randomly removes 50% of events from the pattern. Shorthand for `.undegradeBy(0.5)`
+ * Events that would be removed by degrade are let through by undegrade and vice versa (see second example).
+ *
+ * @name degrade
+ * @memberof Pattern
+ * @returns Pattern
+ * @example
+ * s("hh*8").undegrade()
+ * @example
+ * s("hh*10").layer(
+ *   x => x.degrade().pan(0),
+ *   x => x.undegrade().pan(1)
+ * )
+ */
 export const undegrade = register('undegrade', (pat) => pat._undegradeBy(0.5));
 
 /**
diff --git a/website/src/pages/learn/signals.mdx b/website/src/pages/learn/signals.mdx
index ae64d812..39991c92 100644
--- a/website/src/pages/learn/signals.mdx
+++ b/website/src/pages/learn/signals.mdx
@@ -31,14 +31,14 @@ They can provide streams of numbers that can be sampled at discrete points in ti
 
 <JsDoc client:idle name="square" h={0} />
 
-## Ranges from -1 to 1
-
-There is also `saw2`, `sine2`, `cosine2`, `tri2` and `square2` which have a range from -1 to 1!
-
 ## rand
 
 <JsDoc client:idle name="rand" h={0} />
 
+## Ranges from -1 to 1
+
+There is also `saw2`, `sine2`, `cosine2`, `tri2`, `square2` and `rand2` which have a range from -1 to 1!
+
 ## perlin
 
 <JsDoc client:idle name="perlin" h={0} />
@@ -47,14 +47,34 @@ There is also `saw2`, `sine2`, `cosine2`, `tri2` and `square2` which have a rang
 
 <JsDoc client:idle name="irand" h={0} />
 
+## brand
+
+<JsDoc client:idle name="brand" h={0} />
+
+## brandBy
+
+<JsDoc client:idle name="brandBy" h={0} />
+
 # Random Modifiers
 
 These methods add random behavior to your Patterns.
 
+## choose
+
+<JsDoc client:idle name="choose" h={0} />
+
+## wchoose
+
+<JsDoc client:idle name="wchoose" h={0} />
+
 ## chooseCycles
 
 <JsDoc client:idle name="chooseCycles" h={0} />
 
+## wchooseCycles
+
+<JsDoc client:idle name="wchooseCycles" h={0} />
+
 ## degradeBy
 
 <JsDoc client:idle name="Pattern.degradeBy" h={0} />
@@ -67,6 +87,10 @@ These methods add random behavior to your Patterns.
 
 <JsDoc client:idle name="Pattern.undegradeBy" h={0} />
 
+## undegrade
+
+<JsDoc client:idle name="Pattern.undegrade" h={0} />
+
 ## sometimesBy
 
 <JsDoc client:idle name="Pattern.sometimesBy" h={0} />