From f0e412a44344d1b6b96bd9280f44ad1784c30c94 Mon Sep 17 00:00:00 2001
From: Felix Roos <flix91@gmail.com>
Date: Wed, 14 Sep 2022 23:40:48 +0200
Subject: [PATCH] doc: chooseCycles + mini shorthands

---
 packages/core/signal.mjs | 21 ++++++++++++++-------
 tutorial/MiniRepl.jsx    |  2 +-
 tutorial/tutorial.mdx    |  4 +++-
 3 files changed, 18 insertions(+), 9 deletions(-)

diff --git a/packages/core/signal.mjs b/packages/core/signal.mjs
index b43ecadf..9a4b5fe5 100644
--- a/packages/core/signal.mjs
+++ b/packages/core/signal.mjs
@@ -156,8 +156,8 @@ export const chooseInWith = (pat, xs) => {
 };
 
 /**
- * Chooses randomly from the given list of values.
- * @param  {...any} xs
+ * Chooses randomly from the given list of elements.
+ * @param  {...any} xs values / patterns to choose from.
  * @returns {Pattern} - a continuous pattern.
  */
 export const choose = (...xs) => chooseWith(rand, xs);
@@ -183,6 +183,14 @@ Pattern.prototype.choose2 = function (...xs) {
   return chooseWith(this._fromBipolar(), xs);
 };
 
+/**
+ * Picks one of the elements at random each cycle.
+ * @returns {Pattern}
+ * @example
+ * chooseCycles("bd", "hh", "sd").s().fast(4).out()
+ * @example
+ * "bd | hh | sd".s().fast(4).out()
+ */
 export const chooseCycles = (...xs) => chooseInWith(rand.segment(1), xs);
 
 export const randcat = chooseCycles;
@@ -234,6 +242,8 @@ Pattern.prototype._degradeByWith = function (withPat, x) {
  * @returns Pattern
  * @example
  * s("hh*8").degradeBy(0.2).out()
+ * @example
+ * s("[hh?0.2]*8").out()
  */
 Pattern.prototype._degradeBy = function (x) {
   return this._degradeByWith(rand, x);
@@ -248,6 +258,8 @@ Pattern.prototype._degradeBy = function (x) {
  * @returns Pattern
  * @example
  * s("hh*8").degrade().out()
+ * @example
+ * s("[hh?]*8").out()
  */
 Pattern.prototype.degrade = function () {
   return this._degradeBy(0.5);
@@ -265,11 +277,6 @@ Pattern.prototype.degrade = function () {
  * @returns Pattern
  * @example
  * s("hh*8").undegradeBy(0.2).out()
- * @example
- * stack(
- *  s("hh*8").undegradeBy(0.2),
- *  s("bd*8").degradeBy(0.8)
- * ).out()
  */
 Pattern.prototype._undegradeBy = function (x) {
   return this._degradeByWith(
diff --git a/tutorial/MiniRepl.jsx b/tutorial/MiniRepl.jsx
index 405cd94d..0f18c2b6 100644
--- a/tutorial/MiniRepl.jsx
+++ b/tutorial/MiniRepl.jsx
@@ -15,7 +15,7 @@ export const defaultSynth = new Tone.PolySynth().chain(new Tone.Gain(0.5), Tone.
 samples(
   {
     bd: '808bd/BD0000.WAV',
-    sd: ['808sd/SD0000.WAV', '808sd/SD0010.WAV', '808sd/SD0050.WAV'],
+    sd: ['808sd/SD0010.WAV', '808sd/SD0050.WAV', '808sd/SD0000.WAV'],
     hh: ['hh27/000_hh27closedhh.wav', 'hh/000_hh3closedhh.wav'],
   },
   'https://raw.githubusercontent.com/tidalcycles/Dirt-Samples/master/',
diff --git a/tutorial/tutorial.mdx b/tutorial/tutorial.mdx
index 4ff4a20a..8e1fc75e 100644
--- a/tutorial/tutorial.mdx
+++ b/tutorial/tutorial.mdx
@@ -452,7 +452,9 @@ Stacks the given pattern to the current pattern:
 
 ## Randomness
 
-These methods add random behavior to your Patterns.  
+These methods add random behavior to your Patterns.
+
+{{ 'chooseCycles' | jsdoc }}
 
 {{ 'Pattern.degradeBy' | jsdoc }}