Reference tab sort

packages/core/controls.mjs

@@ -51,6 +51,7 @@ const generic_params = [
    *
    * @name accelerate
    * @param {number | Pattern} amount acceleration.
+   * @superdirtOnly
    * @example
    * s("sax").accelerate("<0 1 2 4 8 16>").slow(2).osc()
    *
@@ -75,19 +76,20 @@ const generic_params = [
    *
    * @name amp
    * @param {number | Pattern} amount gain.
+   * @superdirtOnly
    * @example
    * s("bd*8").amp(".1*2 .5 .1*2 .5 .1 .5").osc()
    *
    */
   ['f', 'amp', 'like @gain@, but linear.'],
-  // TODO: find out why 0 does not work, and it generally seems not right
-  /*
+  /**
    * A pattern of numbers to specify the attack time of an envelope applied to each sample.
+   * [More info about envelopes](/learn/synths-samples-effects/#envelope)
    *
    * @name attack
    * @param {number | Pattern} attack time in seconds.
    * @example
-   * n("c5 e5").s('superpiano').attack("<0 .1>").osc()
+   * note("c3 e3").attack("<0 .1 .5>")
    *
    */
   [
@@ -107,18 +109,36 @@ const generic_params = [
    */
   ['f', 'bank', 'selects sound bank to use'],
 
-  // TODO: find out how this works?
-  /*
-   * Envelope decay time = the time it takes after the attack time to reach the sustain level.
+  /**
+   * Gain envelope decay time = the time it takes after the attack time to reach the sustain level.
+   * [More info about envelopes](/learn/synths-samples-effects/#envelope)
    *
    * @name decay
    * @param {number | Pattern} time decay time in seconds
    * @example
-   * s("sax").cut(1).decay("<.1 .2 .3 .4>").sustain(0).osc()
+   * note("c3 e3").decay("<.1 .2 .3 .4>").sustain(0)
    *
    */
   ['f', 'decay', ''],
+  /**
+   * Gain envelope sustain level. [More info about envelopes](/learn/synths-samples-effects/#envelope)
+   *
+   * @name sustain
+   * @param {number | Pattern} gain sustain level between 0 and 1
+   * @example
+   * note("c3 e3").decay(.2).sustain("<0 .1 .4 .6 1>")
+   *
+   */
   ['f', 'sustain', ''],
+  /**
+   * Gain envelope release time. [More info about envelopes](/learn/synths-samples-effects/#envelope)
+   *
+   * @name release
+   * @param {number | Pattern} time release time in seconds
+   * @example
+   * note("c3 e3 g3 c4").release("<0 .1 .4 .6 1>/2")
+   *
+   */
   [
     'f',
     'release',

test/__snapshots__/examples.test.mjs.snap

@@ -257,6 +257,19 @@ exports[`runs examples > example "apply" example index 0 1`] = `
 ]
 `;
 
+exports[`runs examples > example "attack" example index 0 1`] = `
+[
+  "[ 0/1 → 1/2 | note:c3 attack:0 ]",
+  "[ 1/2 → 1/1 | note:e3 attack:0 ]",
+  "[ 1/1 → 3/2 | note:c3 attack:0.1 ]",
+  "[ 3/2 → 2/1 | note:e3 attack:0.1 ]",
+  "[ 2/1 → 5/2 | note:c3 attack:0.5 ]",
+  "[ 5/2 → 3/1 | note:e3 attack:0.5 ]",
+  "[ 3/1 → 7/2 | note:c3 attack:0 ]",
+  "[ 7/2 → 4/1 | note:e3 attack:0 ]",
+]
+`;
+
 exports[`runs examples > example "bandf" example index 0 1`] = `
 [
   "[ 0/1 → 1/2 | s:bd bandf:1000 ]",
@@ -608,6 +621,19 @@ exports[`runs examples > example "cutoff" example index 0 1`] = `
 ]
 `;
 
+exports[`runs examples > example "decay" example index 0 1`] = `
+[
+  "[ 0/1 → 1/2 | note:c3 decay:0.1 sustain:0 ]",
+  "[ 1/2 → 1/1 | note:e3 decay:0.1 sustain:0 ]",
+  "[ 1/1 → 3/2 | note:c3 decay:0.2 sustain:0 ]",
+  "[ 3/2 → 2/1 | note:e3 decay:0.2 sustain:0 ]",
+  "[ 2/1 → 5/2 | note:c3 decay:0.3 sustain:0 ]",
+  "[ 5/2 → 3/1 | note:e3 decay:0.3 sustain:0 ]",
+  "[ 3/1 → 7/2 | note:c3 decay:0.4 sustain:0 ]",
+  "[ 7/2 → 4/1 | note:e3 decay:0.4 sustain:0 ]",
+]
+`;
+
 exports[`runs examples > example "degrade" example index 0 1`] = `
 [
   "[ 0/1 → 1/8 | s:hh ]",
@@ -2319,6 +2345,27 @@ exports[`runs examples > example "rarely" example index 0 1`] = `
 ]
 `;
 
+exports[`runs examples > example "release" example index 0 1`] = `
+[
+  "[ 0/1 → 1/4 | note:c3 release:0 ]",
+  "[ 1/4 → 1/2 | note:e3 release:0 ]",
+  "[ 1/2 → 3/4 | note:g3 release:0 ]",
+  "[ 3/4 → 1/1 | note:c4 release:0 ]",
+  "[ 1/1 → 5/4 | note:c3 release:0 ]",
+  "[ 5/4 → 3/2 | note:e3 release:0 ]",
+  "[ 3/2 → 7/4 | note:g3 release:0 ]",
+  "[ 7/4 → 2/1 | note:c4 release:0 ]",
+  "[ 2/1 → 9/4 | note:c3 release:0.1 ]",
+  "[ 9/4 → 5/2 | note:e3 release:0.1 ]",
+  "[ 5/2 → 11/4 | note:g3 release:0.1 ]",
+  "[ 11/4 → 3/1 | note:c4 release:0.1 ]",
+  "[ 3/1 → 13/4 | note:c3 release:0.1 ]",
+  "[ 13/4 → 7/2 | note:e3 release:0.1 ]",
+  "[ 7/2 → 15/4 | note:g3 release:0.1 ]",
+  "[ 15/4 → 4/1 | note:c4 release:0.1 ]",
+]
+`;
+
 exports[`runs examples > example "resonance" example index 0 1`] = `
 [
   "[ 0/1 → 1/2 | s:bd cutoff:2000 resonance:0 ]",
@@ -2935,6 +2982,19 @@ exports[`runs examples > example "superimpose" example index 0 1`] = `
 ]
 `;
 
+exports[`runs examples > example "sustain" example index 0 1`] = `
+[
+  "[ 0/1 → 1/2 | note:c3 decay:0.2 sustain:0 ]",
+  "[ 1/2 → 1/1 | note:e3 decay:0.2 sustain:0 ]",
+  "[ 1/1 → 3/2 | note:c3 decay:0.2 sustain:0.1 ]",
+  "[ 3/2 → 2/1 | note:e3 decay:0.2 sustain:0.1 ]",
+  "[ 2/1 → 5/2 | note:c3 decay:0.2 sustain:0.4 ]",
+  "[ 5/2 → 3/1 | note:e3 decay:0.2 sustain:0.4 ]",
+  "[ 3/1 → 7/2 | note:c3 decay:0.2 sustain:0.6 ]",
+  "[ 7/2 → 4/1 | note:e3 decay:0.2 sustain:0.6 ]",
+]
+`;
+
 exports[`runs examples > example "timeCat" example index 0 1`] = `
 [
   "[ 0/1 → 3/4 | note:e3 ]",

website/src/repl/Reference.jsx

@@ -1,7 +1,7 @@
 import jsdocJson from '../../../doc.json';
 const visibleFunctions = jsdocJson.docs
   .filter(({ name, description }) => name && !name.startsWith('_') && !!description)
-  .sort((a, b) => a.meta.filename.localeCompare(b.meta.filename) + a.name.localeCompare(b.name));
+  .sort((a, b) => /* a.meta.filename.localeCompare(b.meta.filename) +  */ a.name.localeCompare(b.name));
 
 export function Reference() {
   return (