From b48fd78cf079f56336f218ab455714459fbc9a50 Mon Sep 17 00:00:00 2001
From: Felix Roos <flix91@gmail.com>
Date: Thu, 31 Aug 2023 12:29:29 +0200
Subject: [PATCH] fm envelope docs

---
 packages/core/controls.mjs         | 56 ++++++++++++++++++++++++++++--
 packages/superdough/synth.mjs      |  2 +-
 website/src/pages/learn/synths.mdx | 16 +++++++++
 3 files changed, 71 insertions(+), 3 deletions(-)

diff --git a/packages/core/controls.mjs b/packages/core/controls.mjs
index 8dba27b8..63ade17b 100644
--- a/packages/core/controls.mjs
+++ b/packages/core/controls.mjs
@@ -118,7 +118,9 @@ const generic_params = [
    * @name fmh
    * @param {number | Pattern} harmonicity
    * @example
-   * note("c e g b").fm(4).fmh("<1 2 1.5 1.61>")
+   * note("c e g b")
+   * .fm(4)
+   * .fmh("<1 2 1.5 1.61>")
    *
    */
   [['fmh', 'fmi'], 'fmh'],
@@ -130,15 +132,65 @@ const generic_params = [
    * @param {number | Pattern} brightness modulation index
    * @synonyms fmi
    * @example
-   * note("c e g b").fm("<0 1 2 8 32>")
+   * note("c e g b")
+   * .fm("<0 1 2 8 32>")
    *
    */
   [['fmi', 'fmh'], 'fm'],
   // fm envelope
+  /**
+   * Ramp type of fm envelope. Exp might be a bit broken..
+   *
+   * @name fmenv
+   * @param {number | Pattern} type lin | exp
+   * @example
+   * note("c e g b")
+   * .fm(4)
+   * .fmdecay(.2)
+   * .fmsustain(.4)
+   * .fmenv("<exp lin>")
+   *
+   */
   ['fmenv'],
+  /**
+   * Attack time for the FM envelope: time it takes to reach maximum modulation
+   *
+   * @name fmattack
+   * @param {number | Pattern} time attack time
+   * @example
+   * note("c e g b")
+   * .fm(4)
+   * .fmattack("<0 .05 .1 .2>")
+   *
+   */
   ['fmattack'],
+  /**
+   * Decay time for the FM envelope: seconds until the sustain level is reached after the attack phase.
+   *
+   * @name fmdecay
+   * @param {number | Pattern} time decay time
+   * @example
+   * note("c e g b")
+   * .fm(4)
+   * .fmdecay("<.01 .05 .1 .2>")
+   * .fmsustain(.4)
+   *
+   */
   ['fmdecay'],
+  /**
+   * Sustain level for the FM envelope: how much modulation is applied after the decay phase
+   *
+   * @name fmsustain
+   * @param {number | Pattern} level sustain level
+   * @example
+   * note("c e g b")
+   * .fm(4)
+   * .fmdecay(.1)
+   * .fmsustain("<1 .75 .5 0>")
+   *
+   */
   ['fmsustain'],
+  // these are not really useful... skipping for now
   ['fmrelease'],
   ['fmvelocity'],
 
diff --git a/packages/superdough/synth.mjs b/packages/superdough/synth.mjs
index 9756ced0..a409d990 100644
--- a/packages/superdough/synth.mjs
+++ b/packages/superdough/synth.mjs
@@ -33,7 +33,7 @@ export function registerSynthSounds() {
           release = 0.01,
           fmh: fmHarmonicity = 1,
           fmi: fmModulationIndex,
-          fmenv: fmEnvelopeType = 'linear',
+          fmenv: fmEnvelopeType = 'lin',
           fmattack: fmAttack,
           fmdecay: fmDecay,
           fmsustain: fmSustain,
diff --git a/website/src/pages/learn/synths.mdx b/website/src/pages/learn/synths.mdx
index 6ebf2613..9c515752 100644
--- a/website/src/pages/learn/synths.mdx
+++ b/website/src/pages/learn/synths.mdx
@@ -38,4 +38,20 @@ Now we not only pattern the notes, but the sound as well!
 
 <JsDoc client:idle name="fmh" h={0} />
 
+### fmattack
+
+<JsDoc client:idle name="fmattack" h={0} />
+
+### fmdecay
+
+<JsDoc client:idle name="fmdecay" h={0} />
+
+### fmsustain
+
+<JsDoc client:idle name="fmsustain" h={0} />
+
+### fmenv
+
+<JsDoc client:idle name="fmenv" h={0} />
+
 Next up: [Audio Effects](/learn/effects)...