Fix #2630: Add jsdoc style documentation (#4066)

* add jsdoc style documentation

* remove getPitchInfo

js/js-export/API/PitchBlocksAPI.js

@@ -27,16 +27,33 @@
  * @classdesc methods are imported by a importMethod function call from MusicBlocks class.
  */
 class PitchBlocksAPI {
+    /**
+     * Plays a note with specified pitch and octave.
+     * @param {string} note - The note name to play (e.g., 'C', 'D', etc.)
+     * @param {number} octave - The octave number for the note
+     * @returns {Promise} Command execution promise
+     */
     playPitch(note, octave) {
         const args = JSInterface.validateArgs("playPitch", [note, octave]);
         return this.runCommand("playPitch", [args[0], args[1], 0, this.turIndex, MusicBlocks.BLK]);
     }
 
+    /**
+     * Steps the pitch up or down by a specified value.
+     * @param {number} value - The number of steps to move (positive for up, negative for down)
+     * @returns {Promise} Command execution promise
+     */
     stepPitch(value) {
         const args = JSInterface.validateArgs("stepPitch", [value]);
         return this.runCommand("stepPitch", [args[0], this.turIndex]);
     }
 
+    /**
+     * Plays the nth pitch in the current modal scale.
+     * @param {number} number - The scale degree to play
+     * @param {number} octave - The octave number
+     * @returns {Promise} Command execution promise
+     */
     playNthModalPitch(number, octave) {
         const args = JSInterface.validateArgs("playNthModalPitch", [number, octave]);
         return this.runCommand("playNthModalPitch", [
@@ -47,66 +64,118 @@ class PitchBlocksAPI {
         ]);
     }
 
+    /**
+     * Plays a pitch specified by its number value.
+     * @param {number} number - The pitch number to play
+     * @returns {Promise} Command execution promise
+     */
     playPitchNumber(number) {
         const args = JSInterface.validateArgs("playPitchNumber", [number]);
         return this.runCommand("playPitchNumber", [args[0], this.turIndex, MusicBlocks.BLK]);
     }
 
+    /**
+     * Plays a note at a specified frequency in Hertz.
+     * @param {number} value - The frequency in Hertz
+     * @returns {Promise} Command execution promise
+     */
     playHertz(value) {
         const args = JSInterface.validateArgs("playHertz", [value]);
         return this.runCommand("playHertz", [args[0], this.turIndex]);
     }
 
+    /**
+     * Sets an accidental (sharp, flat, etc.) for subsequent notes.
+     * @param {string} accidental - The accidental to apply
+     * @param {Function} flow - Flow function to execute after setting accidental
+     * @returns {string} ENDFLOWCOMMAND
+     */
     async setAccidental(accidental, flow) {
         const args = JSInterface.validateArgs("setAccidental", [accidental, flow]);
         await this.runCommand("setAccidental", [args[0], this.turIndex, MusicBlocks.BLK]);
         await args[1]();
         return this.ENDFLOWCOMMAND;
     }
 
+    /**
+     * Transposes subsequent notes by a scalar value.
+     * @param {number} value - The number of scale degrees to transpose
+     * @param {Function} flow - Flow function to execute after transposition
+     * @returns {string} ENDFLOWCOMMAND
+     */
     async setScalarTranspose(value, flow) {
         const args = JSInterface.validateArgs("setScalarTranspose", [value, flow]);
         await this.runCommand("setScalarTranspose", [args[0], this.turIndex]);
         await args[1]();
         return this.ENDFLOWCOMMAND;
     }
 
+    /**
+     * Transposes subsequent notes by a specified number of semitones.
+     * @param {number} value - The number of semitones to transpose
+     * @param {Function} flow - Flow function to execute after transposition
+     * @returns {string} ENDFLOWCOMMAND
+     */
     async setSemitoneTranspose(value, flow) {
         const args = JSInterface.validateArgs("setSemitoneTranspose", [value, flow]);
         await this.runCommand("setSemitoneTranspose", [args[0], this.turIndex]);
         await args[1]();
         return this.ENDFLOWCOMMAND;
     }
 
+    /**
+     * Sets the register (octave range) for subsequent notes.
+     * @param {number} value - The register value to set
+     * @returns {Promise} Command execution promise
+     */
     setRegister(value) {
         const args = JSInterface.validateArgs("setRegister", [value]);
         return this.runCommand("setRegister", [args[0], this.turIndex]);
     }
 
+    /**
+     * Inverts the current pitch sequence based on specified parameters.
+     * @param {string} name - The name of the inversion
+     * @param {number} octave - The octave for the inversion
+     * @param {string} mode - The mode for the inversion
+     * @param {Function} flow - Flow function to execute after inversion
+     * @returns {string} ENDFLOWCOMMAND
+     */
     async invert(name, octave, mode, flow) {
         const args = JSInterface.validateArgs("invert", [name, octave, mode, flow]);
         await this.runCommand("invert", [args[0], args[1], args[2], this.turIndex]);
         await args[3]();
         return this.ENDFLOWCOMMAND;
     }
 
+    /**
+     * Sets the pitch number offset for subsequent notes.
+     * @param {number} pitch - The pitch offset value
+     * @param {number} octave - The octave offset value
+     * @returns {Promise} Command execution promise
+     */
     setPitchNumberOffset(pitch, octave) {
         const args = JSInterface.validateArgs("setPitchNumberOffset", [pitch, octave]);
         return this.runCommand("setPitchNumberOffset", [args[0], args[1], this.turIndex]);
     }
 
+    /**
+     * Converts a number to its corresponding pitch name.
+     * @param {number} number - The number to convert
+     * @returns {string} The pitch name
+     */
     numToPitch(number) {
         const args = JSInterface.validateArgs("numToPitch", [number]);
         return Singer.PitchActions.numToPitch(args[0], "pitch", this.turIndex);
     }
 
+    /**
+     * Converts a number to its corresponding octave.
+     * @param {number} number - The number to convert
+     * @returns {number} The octave number
+     */
     numToOctave(number) {
         const args = JSInterface.validateArgs("numToOctave", [number]);
         return Singer.PitchActions.numToPitch(args[0], "octave", this.turIndex);
     }
-
-    // getPitchInfo(type) {
-    //     let args = JSInterface.validateArgs("getPitchInfo", [type]);
-    //     return Singer.PitchActions.getPitchInfo(args[0], this.turIndex);
-    // }
 }

js/js-export/API/RhythmBlocksAPI.js

@@ -27,45 +27,85 @@
  * @classdesc methods are imported by a importMethod function call from MusicBlocks class.
  */
 class RhythmBlocksAPI {
+    /**
+     * Plays a note with the specified value.
+     * @param {number} value - The value/duration of the note to play
+     * @param {Function} flow - Flow function to execute after playing the note
+     * @returns {string} ENDFLOWCOMMAND
+     */
     async playNote(value, flow) {
         const args = JSInterface.validateArgs("playNote", [value, flow]);
         await this.runCommand("playNote", [args[0], "newnote", this.turIndex, MusicBlocks.BLK]);
         await args[1]();
         return this.ENDFLOWCOMMAND;
     }
 
+    /**
+     * Plays a note with a specified duration in milliseconds.
+     * @param {number} value - The duration in milliseconds
+     * @param {Function} flow - Flow function to execute after playing the note
+     * @returns {string} ENDFLOWCOMMAND
+     */
     async playNoteMillis(value, flow) {
         const args = JSInterface.validateArgs("playNoteMillis", [value, flow]);
         await this.runCommand("playNote", [args[0], "osctime", this.turIndex, MusicBlocks.BLK]);
         await args[1]();
         return this.ENDFLOWCOMMAND;
     }
 
+    /**
+     * Plays a rest (silence) for the current turtle.
+     * @returns {Promise} Command execution promise
+     */
     playRest() {
         return this.runCommand("playRest", [this.turIndex]);
     }
 
+    /**
+     * Adds a rhythmic dot to extend the duration of a note.
+     * @param {number} value - The dot value to apply
+     * @param {Function} flow - Flow function to execute after applying the dot
+     * @returns {string} ENDFLOWCOMMAND
+     */
     async dot(value, flow) {
         const args = JSInterface.validateArgs("dot", [value, flow]);
         await this.runCommand("doRhythmicDot", [args[0], this.turIndex]);
         await args[1]();
         return this.ENDFLOWCOMMAND;
     }
 
+    /**
+     * Ties two notes together.
+     * @param {Function} flow - Flow function to execute after applying the tie
+     * @returns {string} ENDFLOWCOMMAND
+     */
     async tie(flow) {
         const args = JSInterface.validateArgs("tie", [flow]);
         await this.runCommand("doTie", [this.turIndex]);
         await args[1]();
         return this.ENDFLOWCOMMAND;
     }
 
+    /**
+     * Multiplies the duration of a note by a specified factor.
+     * @param {number} factor - The multiplication factor to apply
+     * @param {Function} flow - Flow function to execute after multiplication
+     * @returns {string} ENDFLOWCOMMAND
+     */
     async multiplyNoteValue(factor, flow) {
         const args = JSInterface.validateArgs("multiplyNoteValue", [factor, flow]);
         await this.runCommand("multiplyNoteValue", [args[0], this.turIndex]);
         await args[1]();
         return this.ENDFLOWCOMMAND;
     }
 
+    /**
+     * Applies a swing rhythm effect to notes.
+     * @param {number} swingValue - The amount of swing to apply
+     * @param {number} noteValue - The note value to apply swing to
+     * @param {Function} flow - Flow function to execute after applying swing
+     * @returns {string} ENDFLOWCOMMAND
+     */
     async swing(swingValue, noteValue, flow) {
         const args = JSInterface.validateArgs("multiplyNoteValue", [swingValue, noteValue, flow]);
         await this.runCommand("addSwing", [args[0], args[1], this.turIndex]);

js/js-export/API/ToneBlocksAPI.js

@@ -27,20 +27,41 @@
  * @classdesc methods are imported by a importMethod function call from MusicBlocks class.
  */
 class ToneBlocksAPI {
+    /**
+     * Sets the instrument/timbre for the current turtle.
+     * @param {string} instrument - The name of the instrument to set
+     * @param {Function} flow - Flow function to execute after setting the instrument
+     * @returns {string} ENDFLOWCOMMAND
+     */
     async setInstrument(instrument, flow) {
         const args = JSInterface.validateArgs("setInstrument", [instrument, flow]);
         await this.runCommand("setTimbre", [args[0], this.turIndex]);
         await args[1]();
         return this.ENDFLOWCOMMAND;
     }
 
+    /**
+     * Applies a vibrato effect to the current turtle's sound.
+     * @param {number} intensity - The intensity of the vibrato effect
+     * @param {number} rate - The rate of the vibrato oscillation
+     * @param {Function} flow - Flow function to execute after applying vibrato
+     * @returns {string} ENDFLOWCOMMAND
+     */
     async doVibrato(intensity, rate, flow) {
         const args = JSInterface.validateArgs("doVibrato", [intensity, rate, flow]);
         await this.runCommand("doVibrato", [args[0], args[1], this.turIndex]);
         await args[2]();
         return this.ENDFLOWCOMMAND;
     }
 
+    /**
+     * Applies a chorus effect to the current turtle's sound.
+     * @param {number} chorusRate - The rate of the chorus effect
+     * @param {number} delayTime - The delay time for the chorus
+     * @param {number} chorusDepth - The depth of the chorus effect
+     * @param {Function} flow - Flow function to execute after applying chorus
+     * @returns {string} ENDFLOWCOMMAND
+     */
     async doChorus(chorusRate, delayTime, chorusDepth, flow) {
         const args = JSInterface.validateArgs("doChorus", [
             chorusRate,
@@ -53,27 +74,54 @@ class ToneBlocksAPI {
         return this.ENDFLOWCOMMAND;
     }
 
+    /**
+     * Applies a phaser effect to the current turtle's sound.
+     * @param {number} rate - The rate of the phaser effect
+     * @param {number} octaves - Number of octaves the effect should span
+     * @param {number} baseFrequency - The base frequency for the phaser
+     * @param {Function} flow - Flow function to execute after applying phaser
+     * @returns {string} ENDFLOWCOMMAND
+     */
     async doPhaser(rate, octaves, baseFrequency, flow) {
         const args = JSInterface.validateArgs("doPhaser", [rate, octaves, baseFrequency, flow]);
         await this.runCommand("doPhaser", [args[0], args[1], args[2], this.turIndex]);
         await args[3]();
         return this.ENDFLOWCOMMAND;
     }
 
+    /**
+     * Applies a tremolo effect to the current turtle's sound.
+     * @param {number} frequency - The frequency of the tremolo effect
+     * @param {number} depth - The depth of the tremolo effect
+     * @param {Function} flow - Flow function to execute after applying tremolo
+     * @returns {string} ENDFLOWCOMMAND
+     */
     async doTremolo(frequency, depth, flow) {
         const args = JSInterface.validateArgs("doTremolo", [frequency, depth, flow]);
         await this.runCommand("doTremolo", [args[0], args[1], this.turIndex]);
         await args[2]();
         return this.ENDFLOWCOMMAND;
     }
 
+    /**
+     * Applies a distortion effect to the current turtle's sound.
+     * @param {number} distortion - The amount of distortion to apply (0-1)
+     * @param {Function} flow - Flow function to execute after applying distortion
+     * @returns {string} ENDFLOWCOMMAND
+     */
     async doDistortion(distortion, flow) {
         const args = JSInterface.validateArgs("doDistortion", [distortion, flow]);
         await this.runCommand("doDistortion", [args[0], this.turIndex]);
         await args[1]();
         return this.ENDFLOWCOMMAND;
     }
 
+    /**
+     * Applies a harmonic effect to the current turtle's sound.
+     * @param {number} harmonic - The harmonic number to apply
+     * @param {Function} flow - Flow function to execute after applying harmonic
+     * @returns {string} ENDFLOWCOMMAND
+     */
     async doHarmonic(harmonic, flow) {
         const args = JSInterface.validateArgs("doHarmonic", [harmonic, flow]);
         await this.runCommand("doHarmonic", [args[0], this.turIndex, MusicBlocks.BLK]);