tonal jsdoc

packages/tonal/tonal.mjs

@@ -42,6 +42,38 @@ function scaleOffset(scale, offset, note) {
 }
 
 // Pattern.prototype._transpose = function (intervalOrSemitones: string | number) {
+/**
+ * Change the pitch of each value by the given amount. Expects numbers or note strings as values.
+ * The amount can be given as a number of semitones or as a string in interval short notation.
+ * If you don't care about enharmonic correctness, just use numbers. Otherwise, pass the interval of
+ * the form: ST where S is the degree number and T the type of interval with
+ *
+ * - M = major
+ * - m = minor
+ * - P = perfect
+ * - A = augmented
+ * - d = diminished
+ *
+ * Examples intervals:
+ *
+ * - 1P = unison = 0
+ * - 3M = major third
+ * - 3m = minor third
+ * - 4P = perfect fourth
+ * - 4A = augmented fourth
+ * - 5P = perfect fifth
+ * - 5d = diminished fifth
+ *
+ * @param {string | number} amount Either number of semitones or interval string.
+ * @returns Pattern
+ * @memberof Pattern
+ * @name transpose
+ * @example
+ * "c2 c3".fast(2).transpose("<0 -2 5 3>".slow(2)).transpose(0)
+ * @example
+ * "c2 c3".fast(2).transpose("<1P -2M 4P 3m>".slow(2)).transpose(0)
+ */
+
 Pattern.prototype._transpose = function (intervalOrSemitones) {
   return this._withHap((hap) => {
     const interval = !isNaN(Number(intervalOrSemitones))
@@ -63,6 +95,20 @@ Pattern.prototype._transpose = function (intervalOrSemitones) {
 // e.g. `stack(c3).superimpose(transpose(slowcat(7, 5)))` or
 // or even `stack(c3).superimpose(transpose.slowcat(7, 5))` or
 
+/**
+ * Transposes notes inside the scale by the number of steps.
+ * Expected to be called on a Pattern which already has a {@link Pattern#scale}
+ *
+ * @memberof Pattern
+ * @name scaleTranspose
+ * @param {offset} offset number of steps inside the scale
+ * @returns Pattern
+ * @example
+ * "-8 [2,4,6]"
+ * .scale('C4 bebop major')
+ * .scaleTranspose("<0 -1 -2 -3 -4 -5 -6 -4>")
+ */
+
 Pattern.prototype._scaleTranspose = function (offset /* : number | string */) {
   return this._withHap((hap) => {
     if (!hap.context.scale) {
@@ -74,6 +120,25 @@ Pattern.prototype._scaleTranspose = function (offset /* : number | string */) {
     return hap.withValue(() => scaleOffset(hap.context.scale, Number(offset), hap.value));
   });
 };
+
+/**
+ * Turns numbers into notes in the scale (zero indexed). Also sets scale for other scale operations, like {@link Pattern#scaleTranspose}.
+ *
+ * The scale name has the form "TO? N" wher
+ *
+ * - T = Tonic
+ * - O = Octave (optional, defaults to 3)
+ * - N = Name of scale, available names can be found [here](https://github.com/tonaljs/tonal/blob/main/packages/scale-type/data.ts).
+ *
+ * @memberof Pattern
+ * @name scale
+ * @param {string} scale Name of scale
+ * @returns Pattern
+ * @example 
+ * "0 2 4 6 4 2"
+ * .scale(seq('C2 major', 'C2 minor').slow(2))
+ */
+
 Pattern.prototype._scale = function (scale /* : string */) {
   return this._withHap((hap) => {
     let note = hap.value;