Skip to content

Commit e9cfe9b

Browse files
retrogtxretrogtx
committed
add jsdoc style documentation
1 parent 148a8ce commit e9cfe9b

File tree

3 files changed

+162
-0
lines changed

3 files changed

+162
-0
lines changed

‎js/js-export/API/PitchBlocksAPI.js‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,16 +27,33 @@
2727
* @classdesc methods are imported by a importMethod function call from MusicBlocks class.
2828
*/
2929
class PitchBlocksAPI {
30+
/**
31+
* Plays a note with specified pitch and octave.
32+
* @param {string} note - The note name to play (e.g., 'C', 'D', etc.)
33+
* @param {number} octave - The octave number for the note
34+
* @returns {Promise} Command execution promise
35+
*/
3036
playPitch(note, octave) {
3137
const args = JSInterface.validateArgs("playPitch", [note, octave]);
3238
return this.runCommand("playPitch", [args[0], args[1], 0, this.turIndex, MusicBlocks.BLK]);
3339
}
3440

41+
/**
42+
* Steps the pitch up or down by a specified value.
43+
* @param {number} value - The number of steps to move (positive for up, negative for down)
44+
* @returns {Promise} Command execution promise
45+
*/
3546
stepPitch(value) {
3647
const args = JSInterface.validateArgs("stepPitch", [value]);
3748
return this.runCommand("stepPitch", [args[0], this.turIndex]);
3849
}
3950

51+
/**
52+
* Plays the nth pitch in the current modal scale.
53+
* @param {number} number - The scale degree to play
54+
* @param {number} octave - The octave number
55+
* @returns {Promise} Command execution promise
56+
*/
4057
playNthModalPitch(number, octave) {
4158
const args = JSInterface.validateArgs("playNthModalPitch", [number, octave]);
4259
return this.runCommand("playNthModalPitch", [
@@ -47,59 +64,116 @@ class PitchBlocksAPI {
4764
]);
4865
}
4966

67+
/**
68+
* Plays a pitch specified by its number value.
69+
* @param {number} number - The pitch number to play
70+
* @returns {Promise} Command execution promise
71+
*/
5072
playPitchNumber(number) {
5173
const args = JSInterface.validateArgs("playPitchNumber", [number]);
5274
return this.runCommand("playPitchNumber", [args[0], this.turIndex, MusicBlocks.BLK]);
5375
}
5476

77+
/**
78+
* Plays a note at a specified frequency in Hertz.
79+
* @param {number} value - The frequency in Hertz
80+
* @returns {Promise} Command execution promise
81+
*/
5582
playHertz(value) {
5683
const args = JSInterface.validateArgs("playHertz", [value]);
5784
return this.runCommand("playHertz", [args[0], this.turIndex]);
5885
}
5986

87+
/**
88+
* Sets an accidental (sharp, flat, etc.) for subsequent notes.
89+
* @param {string} accidental - The accidental to apply
90+
* @param {Function} flow - Flow function to execute after setting accidental
91+
* @returns {string} ENDFLOWCOMMAND
92+
*/
6093
async setAccidental(accidental, flow) {
6194
const args = JSInterface.validateArgs("setAccidental", [accidental, flow]);
6295
await this.runCommand("setAccidental", [args[0], this.turIndex, MusicBlocks.BLK]);
6396
await args[1]();
6497
return this.ENDFLOWCOMMAND;
6598
}
6699

100+
/**
101+
* Transposes subsequent notes by a scalar value.
102+
* @param {number} value - The number of scale degrees to transpose
103+
* @param {Function} flow - Flow function to execute after transposition
104+
* @returns {string} ENDFLOWCOMMAND
105+
*/
67106
async setScalarTranspose(value, flow) {
68107
const args = JSInterface.validateArgs("setScalarTranspose", [value, flow]);
69108
await this.runCommand("setScalarTranspose", [args[0], this.turIndex]);
70109
await args[1]();
71110
return this.ENDFLOWCOMMAND;
72111
}
73112

113+
/**
114+
* Transposes subsequent notes by a specified number of semitones.
115+
* @param {number} value - The number of semitones to transpose
116+
* @param {Function} flow - Flow function to execute after transposition
117+
* @returns {string} ENDFLOWCOMMAND
118+
*/
74119
async setSemitoneTranspose(value, flow) {
75120
const args = JSInterface.validateArgs("setSemitoneTranspose", [value, flow]);
76121
await this.runCommand("setSemitoneTranspose", [args[0], this.turIndex]);
77122
await args[1]();
78123
return this.ENDFLOWCOMMAND;
79124
}
80125

126+
/**
127+
* Sets the register (octave range) for subsequent notes.
128+
* @param {number} value - The register value to set
129+
* @returns {Promise} Command execution promise
130+
*/
81131
setRegister(value) {
82132
const args = JSInterface.validateArgs("setRegister", [value]);
83133
return this.runCommand("setRegister", [args[0], this.turIndex]);
84134
}
85135

136+
/**
137+
* Inverts the current pitch sequence based on specified parameters.
138+
* @param {string} name - The name of the inversion
139+
* @param {number} octave - The octave for the inversion
140+
* @param {string} mode - The mode for the inversion
141+
* @param {Function} flow - Flow function to execute after inversion
142+
* @returns {string} ENDFLOWCOMMAND
143+
*/
86144
async invert(name, octave, mode, flow) {
87145
const args = JSInterface.validateArgs("invert", [name, octave, mode, flow]);
88146
await this.runCommand("invert", [args[0], args[1], args[2], this.turIndex]);
89147
await args[3]();
90148
return this.ENDFLOWCOMMAND;
91149
}
92150

151+
/**
152+
* Sets the pitch number offset for subsequent notes.
153+
* @param {number} pitch - The pitch offset value
154+
* @param {number} octave - The octave offset value
155+
* @returns {Promise} Command execution promise
156+
*/
93157
setPitchNumberOffset(pitch, octave) {
94158
const args = JSInterface.validateArgs("setPitchNumberOffset", [pitch, octave]);
95159
return this.runCommand("setPitchNumberOffset", [args[0], args[1], this.turIndex]);
96160
}
97161

162+
/**
163+
* Converts a number to its corresponding pitch name.
164+
* @param {number} number - The number to convert
165+
* @returns {string} The pitch name
166+
*/
98167
numToPitch(number) {
99168
const args = JSInterface.validateArgs("numToPitch", [number]);
100169
return Singer.PitchActions.numToPitch(args[0], "pitch", this.turIndex);
101170
}
102171

172+
/**
173+
* Converts a number to its corresponding octave.
174+
* @param {number} number - The number to convert
175+
* @returns {number} The octave number
176+
*/
103177
numToOctave(number) {
104178
const args = JSInterface.validateArgs("numToOctave", [number]);
105179
return Singer.PitchActions.numToPitch(args[0], "octave", this.turIndex);

‎js/js-export/API/RhythmBlocksAPI.js‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,45 +27,85 @@
2727
* @classdesc methods are imported by a importMethod function call from MusicBlocks class.
2828
*/
2929
class RhythmBlocksAPI {
30+
/**
31+
* Plays a note with the specified value.
32+
* @param {number} value - The value/duration of the note to play
33+
* @param {Function} flow - Flow function to execute after playing the note
34+
* @returns {string} ENDFLOWCOMMAND
35+
*/
3036
async playNote(value, flow) {
3137
const args = JSInterface.validateArgs("playNote", [value, flow]);
3238
await this.runCommand("playNote", [args[0], "newnote", this.turIndex, MusicBlocks.BLK]);
3339
await args[1]();
3440
return this.ENDFLOWCOMMAND;
3541
}
3642

43+
/**
44+
* Plays a note with a specified duration in milliseconds.
45+
* @param {number} value - The duration in milliseconds
46+
* @param {Function} flow - Flow function to execute after playing the note
47+
* @returns {string} ENDFLOWCOMMAND
48+
*/
3749
async playNoteMillis(value, flow) {
3850
const args = JSInterface.validateArgs("playNoteMillis", [value, flow]);
3951
await this.runCommand("playNote", [args[0], "osctime", this.turIndex, MusicBlocks.BLK]);
4052
await args[1]();
4153
return this.ENDFLOWCOMMAND;
4254
}
4355

56+
/**
57+
* Plays a rest (silence) for the current turtle.
58+
* @returns {Promise} Command execution promise
59+
*/
4460
playRest() {
4561
return this.runCommand("playRest", [this.turIndex]);
4662
}
4763

64+
/**
65+
* Adds a rhythmic dot to extend the duration of a note.
66+
* @param {number} value - The dot value to apply
67+
* @param {Function} flow - Flow function to execute after applying the dot
68+
* @returns {string} ENDFLOWCOMMAND
69+
*/
4870
async dot(value, flow) {
4971
const args = JSInterface.validateArgs("dot", [value, flow]);
5072
await this.runCommand("doRhythmicDot", [args[0], this.turIndex]);
5173
await args[1]();
5274
return this.ENDFLOWCOMMAND;
5375
}
5476

77+
/**
78+
* Ties two notes together.
79+
* @param {Function} flow - Flow function to execute after applying the tie
80+
* @returns {string} ENDFLOWCOMMAND
81+
*/
5582
async tie(flow) {
5683
const args = JSInterface.validateArgs("tie", [flow]);
5784
await this.runCommand("doTie", [this.turIndex]);
5885
await args[1]();
5986
return this.ENDFLOWCOMMAND;
6087
}
6188

89+
/**
90+
* Multiplies the duration of a note by a specified factor.
91+
* @param {number} factor - The multiplication factor to apply
92+
* @param {Function} flow - Flow function to execute after multiplication
93+
* @returns {string} ENDFLOWCOMMAND
94+
*/
6295
async multiplyNoteValue(factor, flow) {
6396
const args = JSInterface.validateArgs("multiplyNoteValue", [factor, flow]);
6497
await this.runCommand("multiplyNoteValue", [args[0], this.turIndex]);
6598
await args[1]();
6699
return this.ENDFLOWCOMMAND;
67100
}
68101

102+
/**
103+
* Applies a swing rhythm effect to notes.
104+
* @param {number} swingValue - The amount of swing to apply
105+
* @param {number} noteValue - The note value to apply swing to
106+
* @param {Function} flow - Flow function to execute after applying swing
107+
* @returns {string} ENDFLOWCOMMAND
108+
*/
69109
async swing(swingValue, noteValue, flow) {
70110
const args = JSInterface.validateArgs("multiplyNoteValue", [swingValue, noteValue, flow]);
71111
await this.runCommand("addSwing", [args[0], args[1], this.turIndex]);

‎js/js-export/API/ToneBlocksAPI.js‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,20 +27,41 @@
2727
* @classdesc methods are imported by a importMethod function call from MusicBlocks class.
2828
*/
2929
class ToneBlocksAPI {
30+
/**
31+
* Sets the instrument/timbre for the current turtle.
32+
* @param {string} instrument - The name of the instrument to set
33+
* @param {Function} flow - Flow function to execute after setting the instrument
34+
* @returns {string} ENDFLOWCOMMAND
35+
*/
3036
async setInstrument(instrument, flow) {
3137
const args = JSInterface.validateArgs("setInstrument", [instrument, flow]);
3238
await this.runCommand("setTimbre", [args[0], this.turIndex]);
3339
await args[1]();
3440
return this.ENDFLOWCOMMAND;
3541
}
3642

43+
/**
44+
* Applies a vibrato effect to the current turtle's sound.
45+
* @param {number} intensity - The intensity of the vibrato effect
46+
* @param {number} rate - The rate of the vibrato oscillation
47+
* @param {Function} flow - Flow function to execute after applying vibrato
48+
* @returns {string} ENDFLOWCOMMAND
49+
*/
3750
async doVibrato(intensity, rate, flow) {
3851
const args = JSInterface.validateArgs("doVibrato", [intensity, rate, flow]);
3952
await this.runCommand("doVibrato", [args[0], args[1], this.turIndex]);
4053
await args[2]();
4154
return this.ENDFLOWCOMMAND;
4255
}
4356

57+
/**
58+
* Applies a chorus effect to the current turtle's sound.
59+
* @param {number} chorusRate - The rate of the chorus effect
60+
* @param {number} delayTime - The delay time for the chorus
61+
* @param {number} chorusDepth - The depth of the chorus effect
62+
* @param {Function} flow - Flow function to execute after applying chorus
63+
* @returns {string} ENDFLOWCOMMAND
64+
*/
4465
async doChorus(chorusRate, delayTime, chorusDepth, flow) {
4566
const args = JSInterface.validateArgs("doChorus", [
4667
chorusRate,
@@ -53,27 +74,54 @@ class ToneBlocksAPI {
5374
return this.ENDFLOWCOMMAND;
5475
}
5576

77+
/**
78+
* Applies a phaser effect to the current turtle's sound.
79+
* @param {number} rate - The rate of the phaser effect
80+
* @param {number} octaves - Number of octaves the effect should span
81+
* @param {number} baseFrequency - The base frequency for the phaser
82+
* @param {Function} flow - Flow function to execute after applying phaser
83+
* @returns {string} ENDFLOWCOMMAND
84+
*/
5685
async doPhaser(rate, octaves, baseFrequency, flow) {
5786
const args = JSInterface.validateArgs("doPhaser", [rate, octaves, baseFrequency, flow]);
5887
await this.runCommand("doPhaser", [args[0], args[1], args[2], this.turIndex]);
5988
await args[3]();
6089
return this.ENDFLOWCOMMAND;
6190
}
6291

92+
/**
93+
* Applies a tremolo effect to the current turtle's sound.
94+
* @param {number} frequency - The frequency of the tremolo effect
95+
* @param {number} depth - The depth of the tremolo effect
96+
* @param {Function} flow - Flow function to execute after applying tremolo
97+
* @returns {string} ENDFLOWCOMMAND
98+
*/
6399
async doTremolo(frequency, depth, flow) {
64100
const args = JSInterface.validateArgs("doTremolo", [frequency, depth, flow]);
65101
await this.runCommand("doTremolo", [args[0], args[1], this.turIndex]);
66102
await args[2]();
67103
return this.ENDFLOWCOMMAND;
68104
}
69105

106+
/**
107+
* Applies a distortion effect to the current turtle's sound.
108+
* @param {number} distortion - The amount of distortion to apply (0-1)
109+
* @param {Function} flow - Flow function to execute after applying distortion
110+
* @returns {string} ENDFLOWCOMMAND
111+
*/
70112
async doDistortion(distortion, flow) {
71113
const args = JSInterface.validateArgs("doDistortion", [distortion, flow]);
72114
await this.runCommand("doDistortion", [args[0], this.turIndex]);
73115
await args[1]();
74116
return this.ENDFLOWCOMMAND;
75117
}
76118

119+
/**
120+
* Applies a harmonic effect to the current turtle's sound.
121+
* @param {number} harmonic - The harmonic number to apply
122+
* @param {Function} flow - Flow function to execute after applying harmonic
123+
* @returns {string} ENDFLOWCOMMAND
124+
*/
77125
async doHarmonic(harmonic, flow) {
78126
const args = JSInterface.validateArgs("doHarmonic", [harmonic, flow]);
79127
await this.runCommand("doHarmonic", [args[0], this.turIndex, MusicBlocks.BLK]);

0 commit comments

Comments
 (0)