added documentation for xen() re: uzu/strudel#1944

packages/xen/xen.mjs

@@ -58,6 +58,29 @@ function xenOffset(xenScale, offset, index = 0) {
 // to an edostep within the scale. Returns the pattern with
 // values mapped to the frequencies associated with the given edosteps
 // scaleNameOrRatios: string || number[], steps?: number
+
+/**
+ * Assumes a numerical pattern of EDO steps. Returns a new pattern with all values
+ * mapped to their associated frequency
+ * 
+ * @name xen
+ * @returns Pattern
+ * @memberof Pattern
+ * @param {(string | number[] )} scaleNameOrRatios
+ * @tags music_theory
+ * @example
+ * "0 8 18".xen("31edo").freq().piano()
+ * @example
+ * // You can also use xen with frequency ratios. 
+ * // This is equivalent to the above:
+ * "0 1 2".xen([
+ * Math.pow(2, 0/31),
+ * Math.pow(2, 8/31),
+ * Math.pow(2, 18/31),
+ * ]).freq().piano()
+ */
+
+// TODO support tunings defined in './tunejs.js'
 export const xen = register('xen', function (scaleNameOrRatios, pat) {
   return pat.withHap((hap) => {
     const scale = getXenScale(scaleNameOrRatios);

website/src/pages/learn/xen.mdx

@@ -6,7 +6,7 @@ layout: ../../layouts/MainLayout.astro
 import { MiniRepl } from '../../docs/MiniRepl';
 import { JsDoc } from '../../docs/JsDoc';
 
-# Xen Harmonic Functions
+# Xen Harmonic Functions (experimental)
 
 These functions allow the use of scales other than your typical chromatic 12 based ones.
 
@@ -93,3 +93,14 @@ Note the legato and reverb effects make sure the sound of the strumming gets to
 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.
+
+### xen(scaleOrRatios)
+
+<JsDoc client:idle name="Pattern.xen" h={0} />
+
+{/* <MiniRepl
+  client:idle
+  tune={`
+  "0 8 18".xen("31edo").freq().piano()
+  `}
+/> */}