From 6837d7e5e8a269bd5d229f12e0a3447408b5a149 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Fri, 19 Apr 2019 12:26:21 +1200 Subject: [PATCH 1/4] Midi JSDoc --- libraries/midi/src/Midi.cpp | 55 ++++++++++++++++++ libraries/midi/src/Midi.h | 112 ++++++++++++++++++++++++------------ 2 files changed, 130 insertions(+), 37 deletions(-) diff --git a/libraries/midi/src/Midi.cpp b/libraries/midi/src/Midi.cpp index 1f190111f2..964fd4419a 100644 --- a/libraries/midi/src/Midi.cpp +++ b/libraries/midi/src/Midi.cpp @@ -261,6 +261,61 @@ void Midi::MidiCleanup() { } #endif +/**jsdoc + * A MIDI message. + *

Warning: The status property is NOT a MIDI status value.

+ * @typedef {object} Midi.MidiMessage + * @property {number} device - Device number. + * @property {Midi.RawMidiMessage} raw - Raw MIDI message - {@link Midi.RawMidiMessage}. + * @property {number} status - Channel + status. Legacy value. + * @property {number} channel - Channel: 1 – 16. + * @property {number} type - Status: {@link Midi.MidiStatus}; 8 – 15. + * @property {number} note - Note: 0 – 127. + * @property {number} velocity - Note velocity: 0 – 127. (0 means "note off".) + * @property {number} bend - Pitch bend: -8192 – 8191. + * @property {number} program - Program change: 0 – 127. + */ +/**jsdoc + * An integer DWORD (unsigned 32 bit) message with bits having values as follows: + * + * + * + * + * + * + * + * + * + *
000000000vvvvvvv0nnnnnnn1ssscccc
+ *

Where:

+ * + *

The number in the first bit of each byte denotes whether it is a command (1) or data (0). + * @typedef {number} Midi.RawMidiMessage + */ +/**jsdoc + *

A MIDI status value. The following MIDI status values are supported:

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
ValueDescription
8Note off.
9Note on.
10Polyphonic key pressure.
11Control change.
12Program change.
13Channel pressure.
14Pitch bend.
15System message.
+ * @typedef {number} Midi.MidiStatus + */ void Midi::midiReceived(int device, int raw, int channel, int status, int type, int note, int velocity, int bend, int program) { QVariantMap eventData; eventData["device"] = device; diff --git a/libraries/midi/src/Midi.h b/libraries/midi/src/Midi.h index 081a44f7b6..57c6962b48 100644 --- a/libraries/midi/src/Midi.h +++ b/libraries/midi/src/Midi.h @@ -21,6 +21,12 @@ #include /**jsdoc + * The Midi API provides the ability to connect Interface with musical instruments and other external or virtual + * devices via the MIDI protocol. For further information and examples, see the tutorial: + * Use MIDI to Control Your Environment.

+ * + *

Note: Only works on Windows.

+ * * @namespace Midi * * @hifi-interface @@ -49,88 +55,112 @@ private: void MidiCleanup(); signals: - void midiNote(QVariantMap eventData); - void midiMessage(QVariantMap eventData); - void midiReset(); - - public slots: /**jsdoc - * Send Raw MIDI packet to a particular device. + * Triggered when a connected device sends an output. + * @function Midi.midiNote + * @param {MidiMessage} message - The MIDI message. + * @returns {Signal} + * @deprecated Use {@link Midi.midiMessage|midiMessage} instead. + */ + void midiNote(QVariantMap eventData); + + /**jsdoc + * Triggered when a connected device sends an output. + * @function Midi.midiMessage + * @param {MidiMessage} message - The MIDI message. + * @returns {Signal} + */ + void midiMessage(QVariantMap eventData); + + /**jsdoc + * Triggered when the system detects there was a reset such as when a device is plugged in or unplugged. + * @function Midi.midiReset + * @returns {Signal} + */ + void midiReset(); + +public slots: + + /**jsdoc + * Sends a raw MIDI packet to a particular device. * @function Midi.sendRawDword * @param {number} device - Integer device number. - * @param {number} raw - Integer (DWORD) raw MIDI message. + * @param {Midi.RawMidiMessage} raw - Raw MIDI message. */ Q_INVOKABLE void sendRawDword(int device, int raw); /**jsdoc - * Send MIDI message to a particular device. + * Sends a MIDI message to a particular device. * @function Midi.sendMidiMessage * @param {number} device - Integer device number. * @param {number} channel - Integer channel number. - * @param {number} type - 0x8 is note off, 0x9 is note on (if velocity=0, note off), etc. - * @param {number} note - MIDI note number. - * @param {number} velocity - Note velocity (0 means note off). + * @param {Midi.MidiStatus} type - Integer status value. + * @param {number} note - Note number. + * @param {number} velocity - Note velocity. (0 means "note off".) + * @comment The "type" parameter has that name to match up with {@link Midi.MidiMessage}. */ Q_INVOKABLE void sendMidiMessage(int device, int channel, int type, int note, int velocity); /**jsdoc - * Play a note on all connected devices. + * Plays a note on all connected devices. * @function Midi.playMidiNote - * @param {number} status - 0x80 is note off, 0x90 is note on (if velocity=0, note off), etc. - * @param {number} note - MIDI note number. - * @param {number} velocity - Note velocity (0 means note off). + * @param {MidiStatus} status - Note status. + * @param {number} note - Note number. + * @param {number} velocity - Note velocity. (0 means "note off".) */ Q_INVOKABLE void playMidiNote(int status, int note, int velocity); /**jsdoc - * Turn off all notes on all connected devices. + * Turns off all notes on all connected MIDI devices. * @function Midi.allNotesOff */ Q_INVOKABLE void allNotesOff(); /**jsdoc - * Clean up and re-discover attached devices. + * Cleans up and rediscovers attached MIDI devices. * @function Midi.resetDevices */ Q_INVOKABLE void resetDevices(); /**jsdoc - * Get a list of inputs/outputs. + * Gets a list of MIDI input or output devices. * @function Midi.listMidiDevices - * @param {boolean} output + * @param {boolean} output - true to list output devices, false to list input devices. * @returns {string[]} */ Q_INVOKABLE QStringList listMidiDevices(bool output); /**jsdoc - * Block an input/output by name. + * Blocks a MIDI device's input or output. * @function Midi.blockMidiDevice - * @param {string} name - * @param {boolean} output + * @param {string} name - The name of the MIDI device to block. + * @param {boolean} output - true to block the device's output, false to block its input. */ Q_INVOKABLE void blockMidiDevice(QString name, bool output); /**jsdoc - * Unblock an input/output by name. + * Unblocks a MIDI device's input or output. * @function Midi.unblockMidiDevice - * @param {string} name - * @param {boolean} output + * @param {string} name- The name of the MIDI device to unblock. + * @param {boolean} output - true to block the device's output, false to block its input. */ Q_INVOKABLE void unblockMidiDevice(QString name, bool output); /**jsdoc - * Repeat all incoming notes to all outputs (default disabled). + * Enables or disables repeating all incoming notes to all outputs. (Default is disabled.) * @function Midi.thruModeEnable - * @param {boolean} enable + * @param {boolean} enable - true to enable repeating all incoming notes to all output, false to + * disable. */ Q_INVOKABLE void thruModeEnable(bool enable); /**jsdoc - * Broadcast on all unblocked devices. + * Enables or disables broadcasts to all unblocked devices. * @function Midi.broadcastEnable - * @param {boolean} enable + * @param {boolean} enable - true to have "send" functions broadcast to all devices, false to + * have them send to specific output devices. */ Q_INVOKABLE void broadcastEnable(bool enable); @@ -138,50 +168,58 @@ signals: /// filter by event types /**jsdoc + * Enables or disables note off events. * @function Midi.typeNoteOffEnable - * @param {boolean} enable + * @param {boolean} enable - true to enable, false to disable. */ Q_INVOKABLE void typeNoteOffEnable(bool enable); /**jsdoc + * Enables or disabled note on events. * @function Midi.typeNoteOnEnable - * @param {boolean} enable + * @param {boolean} enable - true to enable, false to disable. */ Q_INVOKABLE void typeNoteOnEnable(bool enable); /**jsdoc + * Enables or disabled ply key pressure events. * @function Midi.typePolyKeyPressureEnable - * @param {boolean} enable + * @param {boolean} enable - true to enable, false to disable. */ Q_INVOKABLE void typePolyKeyPressureEnable(bool enable); /**jsdoc + * Enables or disabled control change events. * @function Midi.typeControlChangeEnable - * @param {boolean} enable + * @param {boolean} enable - true to enable, false to disable. */ Q_INVOKABLE void typeControlChangeEnable(bool enable); /**jsdoc + * Enables or disabled program change events. * @function Midi.typeProgramChangeEnable - * @param {boolean} enable + * @param {boolean} enable - true to enable, false to disable. */ Q_INVOKABLE void typeProgramChangeEnable(bool enable); /**jsdoc + * Enables or disables channel pressure events. * @function Midi.typeChanPressureEnable - * @param {boolean} enable + * @param {boolean} enable - true to enable, false to disable. */ Q_INVOKABLE void typeChanPressureEnable(bool enable); /**jsdoc + * Enables or disabled pitch bend events. * @function Midi.typePitchBendEnable - * @param {boolean} enable + * @param {boolean} enable - true to enable, false to disable. */ Q_INVOKABLE void typePitchBendEnable(bool enable); /**jsdoc + * Enables or disables system message events. * @function Midi.typeSystemMessageEnable - * @param {boolean} enable + * @param {boolean} enable - true to enable, false to disable. */ Q_INVOKABLE void typeSystemMessageEnable(bool enable); From 62cf42732b86cfc1188b3fa3ff48ffd414a013ce Mon Sep 17 00:00:00 2001 From: David Rowe Date: Thu, 25 Apr 2019 17:34:49 +1200 Subject: [PATCH 2/4] Fix up deprecated notice --- libraries/midi/src/Midi.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libraries/midi/src/Midi.h b/libraries/midi/src/Midi.h index 57c6962b48..bca1cc5971 100644 --- a/libraries/midi/src/Midi.h +++ b/libraries/midi/src/Midi.h @@ -61,7 +61,7 @@ signals: * @function Midi.midiNote * @param {MidiMessage} message - The MIDI message. * @returns {Signal} - * @deprecated Use {@link Midi.midiMessage|midiMessage} instead. + * @deprecated This signal is deprecated and will be removed. Use {@link Midi.midiMessage|midiMessage} instead. */ void midiNote(QVariantMap eventData); From e7eaa7815c6fcb98b203dc3e6c6b4b4fbf52c5d5 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Thu, 25 Apr 2019 22:01:03 +1200 Subject: [PATCH 3/4] Misc. JSDoc fixes --- libraries/midi/src/Midi.cpp | 2 +- libraries/midi/src/Midi.h | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/libraries/midi/src/Midi.cpp b/libraries/midi/src/Midi.cpp index 964fd4419a..97075b82c9 100644 --- a/libraries/midi/src/Midi.cpp +++ b/libraries/midi/src/Midi.cpp @@ -266,7 +266,7 @@ void Midi::MidiCleanup() { *

Warning: The status property is NOT a MIDI status value.

* @typedef {object} Midi.MidiMessage * @property {number} device - Device number. - * @property {Midi.RawMidiMessage} raw - Raw MIDI message - {@link Midi.RawMidiMessage}. + * @property {Midi.RawMidiMessage} raw - Raw MIDI messag. * @property {number} status - Channel + status. Legacy value. * @property {number} channel - Channel: 1 – 16. * @property {number} type - Status: {@link Midi.MidiStatus}; 8 – 15. diff --git a/libraries/midi/src/Midi.h b/libraries/midi/src/Midi.h index bca1cc5971..3130379c49 100644 --- a/libraries/midi/src/Midi.h +++ b/libraries/midi/src/Midi.h @@ -59,7 +59,7 @@ signals: /**jsdoc * Triggered when a connected device sends an output. * @function Midi.midiNote - * @param {MidiMessage} message - The MIDI message. + * @param {Midi.MidiMessage} message - The MIDI message. * @returns {Signal} * @deprecated This signal is deprecated and will be removed. Use {@link Midi.midiMessage|midiMessage} instead. */ @@ -68,7 +68,7 @@ signals: /**jsdoc * Triggered when a connected device sends an output. * @function Midi.midiMessage - * @param {MidiMessage} message - The MIDI message. + * @param {Midi.MidiMessage} message - The MIDI message. * @returns {Signal} */ void midiMessage(QVariantMap eventData); From 8458d746cda79f59200b74c2c6b8c01942d7352a Mon Sep 17 00:00:00 2001 From: David Rowe Date: Fri, 3 May 2019 17:07:14 +1200 Subject: [PATCH 4/4] Doc review --- libraries/midi/src/Midi.cpp | 2 +- libraries/midi/src/Midi.h | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/libraries/midi/src/Midi.cpp b/libraries/midi/src/Midi.cpp index 97075b82c9..7f75b3bfb9 100644 --- a/libraries/midi/src/Midi.cpp +++ b/libraries/midi/src/Midi.cpp @@ -266,7 +266,7 @@ void Midi::MidiCleanup() { *

Warning: The status property is NOT a MIDI status value.

* @typedef {object} Midi.MidiMessage * @property {number} device - Device number. - * @property {Midi.RawMidiMessage} raw - Raw MIDI messag. + * @property {Midi.RawMidiMessage} raw - Raw MIDI message. * @property {number} status - Channel + status. Legacy value. * @property {number} channel - Channel: 1 – 16. * @property {number} type - Status: {@link Midi.MidiStatus}; 8 – 15. diff --git a/libraries/midi/src/Midi.h b/libraries/midi/src/Midi.h index 3130379c49..dd2b5fd678 100644 --- a/libraries/midi/src/Midi.h +++ b/libraries/midi/src/Midi.h @@ -143,7 +143,7 @@ public slots: * Unblocks a MIDI device's input or output. * @function Midi.unblockMidiDevice * @param {string} name- The name of the MIDI device to unblock. - * @param {boolean} output - true to block the device's output, false to block its input. + * @param {boolean} output - true to unblock the device's output, false to unblock its input. */ Q_INVOKABLE void unblockMidiDevice(QString name, bool output); @@ -175,28 +175,28 @@ public slots: Q_INVOKABLE void typeNoteOffEnable(bool enable); /**jsdoc - * Enables or disabled note on events. + * Enables or disables note on events. * @function Midi.typeNoteOnEnable * @param {boolean} enable - true to enable, false to disable. */ Q_INVOKABLE void typeNoteOnEnable(bool enable); /**jsdoc - * Enables or disabled ply key pressure events. + * Enables or disables poly key pressure events. * @function Midi.typePolyKeyPressureEnable * @param {boolean} enable - true to enable, false to disable. */ Q_INVOKABLE void typePolyKeyPressureEnable(bool enable); /**jsdoc - * Enables or disabled control change events. + * Enables or disables control change events. * @function Midi.typeControlChangeEnable * @param {boolean} enable - true to enable, false to disable. */ Q_INVOKABLE void typeControlChangeEnable(bool enable); /**jsdoc - * Enables or disabled program change events. + * Enables or disables program change events. * @function Midi.typeProgramChangeEnable * @param {boolean} enable - true to enable, false to disable. */ @@ -210,7 +210,7 @@ public slots: Q_INVOKABLE void typeChanPressureEnable(bool enable); /**jsdoc - * Enables or disabled pitch bend events. + * Enables or disables pitch bend events. * @function Midi.typePitchBendEnable * @param {boolean} enable - true to enable, false to disable. */