Documentation Update

jsdoc/undocumented.mjs

@@ -10,7 +10,7 @@ function getExports(code) {
   let ast;
   try {
     ast = parse(code, {
-      ecmaVersion: 11,
+      ecmaVersion: 'latest',
       sourceType: 'module',
     });
   } catch (err) {
@@ -49,9 +49,7 @@ function getExports(code) {
 }
 
 function isDocumented(name, docs) {
-  return docs.find(
-    (d) => d.name === name || d.tags?.find((t) => t.title === 'synonyms' && t.value.split(', ').includes(name)),
-  );
+  return docs.find((d) => d.name === name || d.synonyms?.includes(name));
 }
 
 async function getUndocumented(path, docs) {

packages/core/pattern.mjs

@@ -2958,6 +2958,7 @@ export const striate = register('striate', function (n, pat) {
 /**
  * Makes the sample fit the given number of cycles by changing the speed.
  * @name loopAt
+ * @synonyms loopat
  * @memberof Pattern
  * @returns Pattern
  * @example
@@ -3071,6 +3072,7 @@ export const fit = register('fit', (pat) =>
  * given by a global clock and this function will be
  * deprecated/removed.
  * @name loopAtCps
+ * @synonyms loopatcps
  * @memberof Pattern
  * @returns Pattern
  * @example

packages/core/signal.mjs

@@ -10,23 +10,56 @@ import Fraction from './fraction.mjs';
 
 import { id, keyAlias, getCurrentKeyboardState } from './util.mjs';
 
+/**
+ * A `signal` consisting of a constant value. Similar to `pure`, except that function
+ * creates a pattern with one event per cycle, whereas this pattern doesn't have an intrinsic
+ * structure.
+ *
+ * @param {*} value The constant value of the resulting pattern
+ * @returns Pattern
+ */
 export function steady(value) {
   // A continuous value
   return new Pattern((state) => [new Hap(undefined, state.span, value)]);
 }
 
+/**
+ * Creates a "signal", an unstructured pattern consisting of a single value that changes
+ * over time.
+ *
+ *
+ * @param {*} func
+ * @returns Pattern
+ */
 export const signal = (func) => {
   const query = (state) => [new Hap(undefined, state.span, func(state.span.midpoint()))];
   return new Pattern(query);
 };
 
+/**
+ * An inverse sawtooth signal between 1 and 0.
+ *
+ * @type {Pattern}
+ * @example
+ * note("<c3 [eb3,g3] g2 [g3,bb3]>*8")
+ * .clip(isaw.slow(2))
+ * @example
+ * n(isaw.range(0,8).segment(8))
+ * .scale('C major')
+ */
 export const isaw = signal((t) => 1 - (t % 1));
+
+/**
+ * Variant of `isaw` that ranges between 1 and -1.
+ *
+ * @type {Pattern}
+ */
 export const isaw2 = isaw.toBipolar();
 
 /**
  *  A sawtooth signal between 0 and 1.
  *
- * @return {Pattern}
+ * @type {Pattern}
  * @example
  * note("<c3 [eb3,g3] g2 [g3,bb3]>*8")
  * .clip(saw.slow(2))
@@ -36,8 +69,19 @@ export const isaw2 = isaw.toBipolar();
  *
  */
 export const saw = signal((t) => t % 1);
+
+/**
+ * Variant of `saw` that ranges between -1 and 1.
+ *
+ * @type {Pattern}
+ */
 export const saw2 = saw.toBipolar();
 
+/**
+ * Variant of `sine` that ranges between -1 and 1.
+ *
+ * @type {Pattern}
+ */
 export const sine2 = signal((t) => Math.sin(Math.PI * 2 * t));
 
 /**
@@ -61,6 +105,12 @@ export const sine = sine2.fromBipolar();
  *
  */
 export const cosine = sine._early(Fraction(1).div(4));
+
+/**
+ * Variant of `cosine` that ranges between -1 and 1.
+ *
+ * @type {Pattern}
+ */
 export const cosine2 = sine2._early(Fraction(1).div(4));
 
 /**
@@ -72,6 +122,12 @@ export const cosine2 = sine2._early(Fraction(1).div(4));
  *
  */
 export const square = signal((t) => Math.floor((t * 2) % 2));
+
+/**
+ * Variant of `square` that ranges between -1 and 1.
+ *
+ * @type {Pattern}
+ */
 export const square2 = square.toBipolar();
 
 /**
@@ -83,13 +139,25 @@ export const square2 = square.toBipolar();
  *
  */
 export const tri = fastcat(isaw, saw);
+
+/**
+ * Variant of `tri` that ranges between -1 and 1.
+ *
+ * @type {Pattern}
+ */
 export const tri2 = fastcat(isaw2, saw2);
 
+/**
+ * The current cycle count as a signal.
+ *
+ * @type {Pattern}
+ */
 export const time = signal(id);
 
 /**
  *  The mouse's x position value ranges from 0 to 1.
  * @name mousex
+ * @synonyms mouseX
  * @return {Pattern}
  * @example
  * n(mousex.segment(4).range(0,7)).scale("C:minor")
@@ -99,6 +167,7 @@ export const time = signal(id);
 /**
  *  The mouse's y position value ranges from 0 to 1.
  * @name mousey
+ * @synonyms mouseY
  * @return {Pattern}
  * @example
  * n(mousey.segment(4).range(0,7)).scale("C:minor")
@@ -148,10 +217,6 @@ const timeToRandsPrime = (seed, n) => {
 
 const timeToRands = (t, n) => timeToRandsPrime(timeToIntSeed(t), n);
 
-/**
- *
- */
-
 /**
  * A discrete pattern of numbers from 0 to n-1
  * @example

test/__snapshots__/examples.test.mjs.snap

@@ -3884,6 +3884,96 @@ exports[`runs examples > example "iresponse" example index 0 1`] = `
 ]
 `;
 
+exports[`runs examples > example "isaw" example index 0 1`] = `
+[
+  "[ 0/1 → 1/8 | note:c3 clip:0.96875 ]",
+  "[ 1/8 → 1/4 | note:eb3 clip:0.90625 ]",
+  "[ 1/8 → 1/4 | note:g3 clip:0.90625 ]",
+  "[ 1/4 → 3/8 | note:g2 clip:0.84375 ]",
+  "[ 3/8 → 1/2 | note:g3 clip:0.78125 ]",
+  "[ 3/8 → 1/2 | note:bb3 clip:0.78125 ]",
+  "[ 1/2 → 5/8 | note:c3 clip:0.71875 ]",
+  "[ 5/8 → 3/4 | note:eb3 clip:0.65625 ]",
+  "[ 5/8 → 3/4 | note:g3 clip:0.65625 ]",
+  "[ 3/4 → 7/8 | note:g2 clip:0.59375 ]",
+  "[ 7/8 → 1/1 | note:g3 clip:0.53125 ]",
+  "[ 7/8 → 1/1 | note:bb3 clip:0.53125 ]",
+  "[ 1/1 → 9/8 | note:c3 clip:0.46875 ]",
+  "[ 9/8 → 5/4 | note:eb3 clip:0.40625 ]",
+  "[ 9/8 → 5/4 | note:g3 clip:0.40625 ]",
+  "[ 5/4 → 11/8 | note:g2 clip:0.34375 ]",
+  "[ 11/8 → 3/2 | note:g3 clip:0.28125 ]",
+  "[ 11/8 → 3/2 | note:bb3 clip:0.28125 ]",
+  "[ 3/2 → 13/8 | note:c3 clip:0.21875 ]",
+  "[ 13/8 → 7/4 | note:eb3 clip:0.15625 ]",
+  "[ 13/8 → 7/4 | note:g3 clip:0.15625 ]",
+  "[ 7/4 → 15/8 | note:g2 clip:0.09375 ]",
+  "[ 15/8 → 2/1 | note:g3 clip:0.03125 ]",
+  "[ 15/8 → 2/1 | note:bb3 clip:0.03125 ]",
+  "[ 2/1 → 17/8 | note:c3 clip:0.96875 ]",
+  "[ 17/8 → 9/4 | note:eb3 clip:0.90625 ]",
+  "[ 17/8 → 9/4 | note:g3 clip:0.90625 ]",
+  "[ 9/4 → 19/8 | note:g2 clip:0.84375 ]",
+  "[ 19/8 → 5/2 | note:g3 clip:0.78125 ]",
+  "[ 19/8 → 5/2 | note:bb3 clip:0.78125 ]",
+  "[ 5/2 → 21/8 | note:c3 clip:0.71875 ]",
+  "[ 21/8 → 11/4 | note:eb3 clip:0.65625 ]",
+  "[ 21/8 → 11/4 | note:g3 clip:0.65625 ]",
+  "[ 11/4 → 23/8 | note:g2 clip:0.59375 ]",
+  "[ 23/8 → 3/1 | note:g3 clip:0.53125 ]",
+  "[ 23/8 → 3/1 | note:bb3 clip:0.53125 ]",
+  "[ 3/1 → 25/8 | note:c3 clip:0.46875 ]",
+  "[ 25/8 → 13/4 | note:eb3 clip:0.40625 ]",
+  "[ 25/8 → 13/4 | note:g3 clip:0.40625 ]",
+  "[ 13/4 → 27/8 | note:g2 clip:0.34375 ]",
+  "[ 27/8 → 7/2 | note:g3 clip:0.28125 ]",
+  "[ 27/8 → 7/2 | note:bb3 clip:0.28125 ]",
+  "[ 7/2 → 29/8 | note:c3 clip:0.21875 ]",
+  "[ 29/8 → 15/4 | note:eb3 clip:0.15625 ]",
+  "[ 29/8 → 15/4 | note:g3 clip:0.15625 ]",
+  "[ 15/4 → 31/8 | note:g2 clip:0.09375 ]",
+  "[ 31/8 → 4/1 | note:g3 clip:0.03125 ]",
+  "[ 31/8 → 4/1 | note:bb3 clip:0.03125 ]",
+]
+`;
+
+exports[`runs examples > example "isaw" example index 1 1`] = `
+[
+  "[ 0/1 → 1/8 | note:D4 ]",
+  "[ 1/8 → 1/4 | note:C4 ]",
+  "[ 1/4 → 3/8 | note:B3 ]",
+  "[ 3/8 → 1/2 | note:A3 ]",
+  "[ 1/2 → 5/8 | note:G3 ]",
+  "[ 5/8 → 3/4 | note:F3 ]",
+  "[ 3/4 → 7/8 | note:E3 ]",
+  "[ 7/8 → 1/1 | note:D3 ]",
+  "[ 1/1 → 9/8 | note:D4 ]",
+  "[ 9/8 → 5/4 | note:C4 ]",
+  "[ 5/4 → 11/8 | note:B3 ]",
+  "[ 11/8 → 3/2 | note:A3 ]",
+  "[ 3/2 → 13/8 | note:G3 ]",
+  "[ 13/8 → 7/4 | note:F3 ]",
+  "[ 7/4 → 15/8 | note:E3 ]",
+  "[ 15/8 → 2/1 | note:D3 ]",
+  "[ 2/1 → 17/8 | note:D4 ]",
+  "[ 17/8 → 9/4 | note:C4 ]",
+  "[ 9/4 → 19/8 | note:B3 ]",
+  "[ 19/8 → 5/2 | note:A3 ]",
+  "[ 5/2 → 21/8 | note:G3 ]",
+  "[ 21/8 → 11/4 | note:F3 ]",
+  "[ 11/4 → 23/8 | note:E3 ]",
+  "[ 23/8 → 3/1 | note:D3 ]",
+  "[ 3/1 → 25/8 | note:D4 ]",
+  "[ 25/8 → 13/4 | note:C4 ]",
+  "[ 13/4 → 27/8 | note:B3 ]",
+  "[ 27/8 → 7/2 | note:A3 ]",
+  "[ 7/2 → 29/8 | note:G3 ]",
+  "[ 29/8 → 15/4 | note:F3 ]",
+  "[ 15/4 → 31/8 | note:E3 ]",
+  "[ 31/8 → 4/1 | note:D3 ]",
+]
+`;
+
 exports[`runs examples > example "iter" example index 0 1`] = `
 [
   "[ 0/1 → 1/4 | note:A3 ]",