From 77ced19144a775bba1955f463ff5b6822a0fb9b1 Mon Sep 17 00:00:00 2001
From: tyow <cute.oil5122@fastmail.com>
Date: Sat, 24 Jan 2026 14:18:51 -0500
Subject: [PATCH] added jsdoc documentation for tune re uzu/strudel#1944

---
 packages/xen/tune.mjs           | 31 +++++++++++++++++++++++++++++--
 packages/xen/xen.mjs            | 11 ++++++-----
 website/src/pages/learn/xen.mdx | 17 +++++++++++++++++
 3 files changed, 52 insertions(+), 7 deletions(-)

diff --git a/packages/xen/tune.mjs b/packages/xen/tune.mjs
index 22b345695..1f7076b93 100644
--- a/packages/xen/tune.mjs
+++ b/packages/xen/tune.mjs
@@ -7,9 +7,36 @@ This program is free software: you can redistribute it and/or modify it under th
 import Tune from './tunejs.js';
 import { register } from '@strudel/core';
 
-// Tune.scale seems to be in ratio format
-// 
 
+/**
+ * Assumes a numerical pattern of EDO steps. Accepts a scale name or list of frequencies (see all available names at the link on the reference). Returns a new pattern with all values mapped to a frequency ratio. Similar to `xen`.
+ * @name tune
+ * @returns Pattern
+ * @memberof Pattern
+ * @param {(string | number[] )} scale
+ * @example
+ * "0 1 2 3 4 5".tune("hexany15").mul("220").freq()
+ * @example
+ * // You can set your root to be a 
+ * // particular note with getFreq:
+ * `"4 8 9 10 - - 5 7 9 11 - -".tune("tranh3")
+ *   .mul(getFreq('c3'))
+ *   .freq().clip(.5).room(1)`
+ * @example
+ * // You can also give tune a list of 
+ * // frequencies to use as the scale:
+ * "0 1 2 3 4".tune([
+ *   261.6255653006, 
+ *   302.72962012827, 
+ *   350.29154279212, 
+ *   405.32593044476, 
+ *   469.00678383895, 
+ *   523.2511306012
+ * ]).mul(220).freq();
+ * @tags tonal
+*/
+
+// Tune.scale seems to be in ratio format
 export const tune = register('tune', (scale, pat) => {
   const tune = new Tune();
   if (!tune.isValidScale(scale)) {
diff --git a/packages/xen/xen.mjs b/packages/xen/xen.mjs
index 33ea7ea19..15e5291c4 100644
--- a/packages/xen/xen.mjs
+++ b/packages/xen/xen.mjs
@@ -29,6 +29,7 @@ function withBase(freq, scale) {
 const defaultBase = 220;
 
 // Assumes a base of 220. Returns a filtered scale based on 'indices'
+// NOTE: indices functionality is unused
 function getXenScale(scale, indices) {
   let tune = new Tune()
   if (typeof scale === 'string') {
@@ -66,14 +67,13 @@ function xenOffset(xenScale, offset, index = 0) {
 // scaleNameOrRatios: string || number[], steps?: number
 
 /**
- * Assumes a numerical pattern of EDO steps. Returns a new pattern with all values
- * mapped to their associated frequency
+ * Assumes a numerical pattern of EDO steps. Accepts all scale names of `tune` as well as any arbitrary edo scale. Returns a new pattern with all values mapped to their associated frequency, assuming a base frequency of 220hz.
  * 
  * @name xen
  * @returns Pattern
  * @memberof Pattern
  * @param {(string | number[] )} scaleNameOrRatios
- * @tags music_theory
+ * @tags tonal
  * @example
  * // A major tried in 31edo:
  * "0 8 18".xen("31edo").freq().piano()
@@ -93,8 +93,9 @@ function xenOffset(xenScale, offset, index = 0) {
  * // "0 1 2 3 4 5".tune("hexany15").mul("220").freq()
  */
 
-// TODO how do you reference another function in jsdoc (tune, above)
-// TODO support tunings defined in './tunejs.js'
+// TODO feat: change root frequency
+// TODO add explanation for what "31edo" etc. are
+// TODO (maybe): should this return freq ratios like tune does, for parity's sake?
 export const xen = register('xen', function (scaleNameOrRatios, pat) {
   return pat.withHaps((haps) => {
     haps = haps.map(hap=>{
diff --git a/website/src/pages/learn/xen.mdx b/website/src/pages/learn/xen.mdx
index 584d91b13..b32c93c85 100644
--- a/website/src/pages/learn/xen.mdx
+++ b/website/src/pages/learn/xen.mdx
@@ -13,6 +13,7 @@ import { JsDoc } from '../../docs/JsDoc';
 These functions allow the use of scales other than your typical chromatic 12 based ones.
 
 ### tune(scale)
+{/* TODO (maybe): combine jsdoc things in tune.mjs with here */}
 
 <JsDoc client:idle name="tune" h={0} />
 
@@ -96,6 +97,22 @@ tones sound even more alive, too.
 
 The `tranh3` tuning has a similar set of notes, with two clashing. You might trying plugging that in above and see if you find a favorite strumming pattern.
 
+You can also give tune a list of frequencies to use as the scale:
+
+<MiniRepl
+  client:idle
+  tune={`"0 1 2 3 4".tune([
+    261.6255653006, 
+    302.72962012827, 
+    350.29154279212, 
+    405.32593044476, 
+    469.00678383895, 
+    523.2511306012
+  ]).mul(220).freq();`}
+/>
+
 ### xen(scaleOrRatios)
 
+{/* TODO add explanation of EDO to documentation */}
+
 <JsDoc client:idle name="Pattern.xen" h={0} />
\ No newline at end of file