Stub out Audio JSDoc

interface/src/scripting/Audio.h

@@ -26,7 +26,7 @@ class Audio : public AudioScriptingInterface, protected ReadWriteLockable {
     SINGLETON_DEPENDENCY
 
     /**jsdoc
-     * The Audio API features tools to help control audio contexts and settings.
+     * The <code>Audio</code> API ... TODO
      *
      * @namespace Audio
      *
@@ -35,12 +35,13 @@ class Audio : public AudioScriptingInterface, protected ReadWriteLockable {
      * @hifi-server-entity
      * @hifi-assignment-client
      *
-     * @property {boolean} muted
-     * @property {boolean} noiseReduction
-     * @property {number} inputVolume
-     * @property {number} inputLevel <em>Read-only.</em>
-     * @property {string} context <em>Read-only.</em>
-     * @property {} devices <em>Read-only.</em>
+     * @property {boolean} muted - <code>true</code> if TODO, otherwise <code>false</code>.
+     * @property {boolean} noiseReduction - <code>true</code> if TODO, otherwise <code>false</code>.
+     * @property {number} inputVolume - TODO
+     * @property {number} inputLevel - TODO <em>Read-only.</em>
+     * @property {string} context - TODO <em>Read-only.</em>
+     * @property {object} devices <em>Read-only.</em> <strong>Deprecated:</strong> This property is deprecated and will be 
+     *     removed.
      */
  
     Q_PROPERTY(bool muted READ isMuted WRITE setMuted NOTIFY mutedChanged)
@@ -69,87 +70,100 @@ public:
 
     /**jsdoc
      * @function Audio.setInputDevice
-     * @param {} device
+     * @param {object} device
      * @param {boolean} isHMD 
+     * @deprecated This function is deprecated and will be removed.
      */
     Q_INVOKABLE void setInputDevice(const QAudioDeviceInfo& device, bool isHMD);
 
     /**jsdoc
      * @function Audio.setOutputDevice
-     * @param {} device
+     * @param {object} device
      * @param {boolean} isHMD
+     * @deprecated This function is deprecated and will be removed.
      */
     Q_INVOKABLE void setOutputDevice(const QAudioDeviceInfo& device, bool isHMD);
 
     /**jsdoc
+     * TODO
      * @function Audio.setReverb
-     * @param {boolean} enable
+     * @param {boolean} enable - TODO
      */
     Q_INVOKABLE void setReverb(bool enable);
     
     /**jsdoc
+     * TODO
      * @function Audio.setReverbOptions
-     * @param {AudioEffectOptions} options
+     * @param {AudioEffectOptions} options - TODO
      */
     Q_INVOKABLE void setReverbOptions(const AudioEffectOptions* options);
    
     /**jsdoc
+     * TODO
      * @function Audio.startRecording
-     * @param {string} filename
-     * @returns {boolean}
+     * @param {string} filename - TODO
+     * @returns {boolean} <code>true</code> if TODO, otherwise <code>false</code>.
      */
     Q_INVOKABLE bool startRecording(const QString& filename);
     
     /**jsdoc
+     * TODO
      * @function Audio.stopRecording
      */
     Q_INVOKABLE void stopRecording();
 
     /**jsdoc
+     * TODO
      * @function Audio.getRecording
-     * @returns {boolean}
+     * @returns {boolean} <code>true</code> if TODO, otherwise <code>false</code>.
      */
     Q_INVOKABLE bool getRecording();
 
 signals:
 
     /**jsdoc
+     * Triggered when ... TODO
      * @function Audio.nop
      * @returns {Signal}
      */
     void nop();
 
     /**jsdoc
+     * Triggered when ... TODO
      * @function Audio.mutedChanged
-     * @param {boolean} isMuted
+     * @param {boolean} isMuted - TODO
      * @returns {Signal}
      */
     void mutedChanged(bool isMuted);
     
     /**jsdoc
+     * Triggered when ... TODO
      * @function Audio.noiseReductionChanged
-     * @param {boolean} isEnabled
+     * @param {boolean} isEnabled - TODO
      * @returns {Signal}
      */
     void noiseReductionChanged(bool isEnabled);
 
     /**jsdoc
+     * Triggered when ... TODO
      * @function Audio.inputVolumeChanged
-     * @param {number} volume
+     * @param {number} volume - TODO
      * @returns {Signal}
      */
     void inputVolumeChanged(float volume);
 
     /**jsdoc
+     * Triggered when ... TODO
      * @function Audio.inputLevelChanged
-     * @param {number} level
+     * @param {number} level - TODO
      * @returns {Signal}
      */
     void inputLevelChanged(float level);
 
     /**jsdoc
+     * Triggered when ... TODO
      * @function Audio.contextChanged
-     * @param {string} context
+     * @param {string} context - TODO
      * @returns {Signal}
      */
     void contextChanged(const QString& context);
@@ -158,7 +172,7 @@ public slots:
 
     /**jsdoc
      * @function Audio.onContextChanged
-     * @returns {Signal}
+     * @deprecated This function is deprecated and will be removed.
      */
     void onContextChanged();
 

libraries/audio/src/AudioEffectOptions.cpp

@@ -59,28 +59,29 @@ static void setOption(QScriptValue arguments, const QString name, float defaultV
 }
 
 /**jsdoc
+ * TODO
  * @typedef {object} AudioEffectOptions.ReverbOptions
- * @property {number} bandwidth
- * @property {number} preDelay
- * @property {number} lateDelay
- * @property {number} reverbTime
- * @property {number} earlyDiffusion
- * @property {number} lateDiffusion
- * @property {number} roomSize
- * @property {number} density
- * @property {number} bassMult
- * @property {number} bassFreq
- * @property {number} highGain
- * @property {number} highFreq
- * @property {number} modRate
- * @property {number} modDepth
- * @property {number} earlyGain
- * @property {number} lateGain
- * @property {number} earlyMixLeft
- * @property {number} earlyMixRight
- * @property {number} lateMixLeft
- * @property {number} lateMixRight
- * @property {number} wetDryMix
+ * @property {number} bandwidth - TODO
+ * @property {number} preDelay - TODO
+ * @property {number} lateDelay - TODO
+ * @property {number} reverbTime - TODO
+ * @property {number} earlyDiffusion - TODO
+ * @property {number} lateDiffusion - TODO
+ * @property {number} roomSize - TODO
+ * @property {number} density - TODO
+ * @property {number} bassMult - TODO
+ * @property {number} bassFreq - TODO
+ * @property {number} highGain - TODO
+ * @property {number} highFreq - TODO
+ * @property {number} modRate - TODO
+ * @property {number} modDepth - TODO
+ * @property {number} earlyGain - TODO
+ * @property {number} lateGain - TODO
+ * @property {number} earlyMixLeft - TODO
+ * @property {number} earlyMixRight - TODO
+ * @property {number} lateMixLeft - TODO
+ * @property {number} lateMixRight - TODO
+ * @property {number} wetDryMix - TODO
  */
 AudioEffectOptions::AudioEffectOptions(QScriptValue arguments) {
     setOption(arguments, BANDWIDTH_HANDLE, BANDWIDTH_DEFAULT, _bandwidth);

libraries/audio/src/AudioEffectOptions.h

@@ -16,35 +16,38 @@
 #include <QtScript/QScriptEngine>
 
 /**jsdoc
+ * TODO
+ * Used in the {@link Audio} API.
+ *
  * @class AudioEffectOptions
- * @param {AudioEffectOptions.ReverbOptions} [reverbOptions=null]
+ * @param {AudioEffectOptions.ReverbOptions} [reverbOptions=null] - TODO
  *
  * @hifi-interface
  * @hifi-client-entity
  * @hifi-server-entity
  * @hifi-assignment-client
  *
- * @property {number} bandwidth=10000
- * @property {number} preDelay=20
- * @property {number} lateDelay=0
- * @property {number} reverbTime=2
- * @property {number} earlyDiffusion=100
- * @property {number} lateDiffusion=100
- * @property {number} roomSize=50
- * @property {number} density=100
- * @property {number} bassMult=1.5
- * @property {number} bassFreq=250
- * @property {number} highGain=-6
- * @property {number} highFreq=3000
- * @property {number} modRate=2.3
- * @property {number} modDepth=50
- * @property {number} earlyGain=0
- * @property {number} lateGain=0
- * @property {number} earlyMixLeft=20
- * @property {number} earlyMixRight=20
- * @property {number} lateMixLeft=90
- * @property {number} lateMixRight=90
- * @property {number} wetDryMix=50
+ * @property {number} bandwidth=10000 - TODO
+ * @property {number} preDelay=20 - TODO
+ * @property {number} lateDelay=0 - TODO
+ * @property {number} reverbTime=2 - TODO
+ * @property {number} earlyDiffusion=100 - TODO
+ * @property {number} lateDiffusion=100 - TODO
+ * @property {number} roomSize=50 - TODO
+ * @property {number} density=100 - TODO
+ * @property {number} bassMult=1.5 - TODO
+ * @property {number} bassFreq=250 - TODO
+ * @property {number} highGain=-6 - TODO
+ * @property {number} highFreq=3000 - TODO
+ * @property {number} modRate=2.3 - TODO
+ * @property {number} modDepth=50 - TODO
+ * @property {number} earlyGain=0 - TODO
+ * @property {number} lateGain=0 - TODO
+ * @property {number} earlyMixLeft=20 - TODO
+ * @property {number} earlyMixRight=20 - TODO
+ * @property {number} lateMixLeft=90 - TODO
+ * @property {number} lateMixRight=90 - TODO
+ * @property {number} wetDryMix=50 - TODO
  */
 
 class AudioEffectOptions : public QObject {

libraries/audio/src/AudioInjectorOptions.cpp

@@ -45,6 +45,18 @@ QScriptValue injectorOptionsToScriptValue(QScriptEngine* engine, const AudioInje
     return obj;
 }
 
+/**jsdoc
+ * TODO
+ * @typedef {object} AudioInjector.AudioInjectorOptions
+ * @property {Vec3} position=Vec3.ZERO - TODO
+ * @property {Quat} orientation=Quat.IDENTITY - TODO
+ * @property {number} volume=1 - TODO
+ * @property {boolean} loop=false - <code>true</code> if TODO, otherwise <code>false</code>.
+ * @property {boolean} ignorePenumbra=false - <code>true</code> if TODO, otherwise <code>false</code>.
+ * @property {boolean} localOnly=false - <code>true</code> if TODO, otherwise <code>false</code>.
+ * @property {number} secondOffset=0 - TODO
+ * @property {number} pitch=1 - TODO
+ */
 void injectorOptionsFromScriptValue(const QScriptValue& object, AudioInjectorOptions& injectorOptions) {
     if (!object.isObject()) {
         qWarning() << "Audio injector options is not an object.";

libraries/audio/src/Sound.h

@@ -79,6 +79,9 @@ private:
 typedef QSharedPointer<Sound> SharedSoundPointer;
 
 /**jsdoc
+ * TODO
+ * Created by {@link SoundCache.getSound}.
+ *
  * @class SoundObject
  * 
  * @hifi-interface
@@ -86,8 +89,8 @@ typedef QSharedPointer<Sound> SharedSoundPointer;
  * @hifi-server-entity
  * @hifi-assignment-client
  *
- * @property {boolean} downloaded
- * @property {number} duration
+ * @property {boolean} downloaded - <code>true</code> if TODO, otherwise <code>false</code>.
+ * @property {number} duration - TODO
  */
 class SoundScriptingInterface : public QObject {
     Q_OBJECT
@@ -103,6 +106,7 @@ public:
     float getDuration() { return _sound->getDuration(); }
 
 /**jsdoc
+ * Triggered when TODO
  * @function SoundObject.ready
  * @returns {Signal}
  */

libraries/script-engine/src/AudioScriptingInterface.h

@@ -35,91 +35,96 @@ protected:
     // these methods are protected to stop C++ callers from calling, but invokable from script
 
     /**jsdoc
+     * TODO
      * @function Audio.playSound
-     * @param {} sound
-     * @param {} [injectorOptions=null]
-     * @returns {object}
+     * @param {SoundObject} sound - TODO
+     * @param {AudioInjector.AudioInjectorOptions} [injectorOptions={}] - TODO
+     * @returns {AudioInjector} TODO
      */
     Q_INVOKABLE ScriptAudioInjector* playSound(SharedSoundPointer sound, const AudioInjectorOptions& injectorOptions = AudioInjectorOptions());
 
     /**jsdoc
+     * TODO
      * @function Audio.playSystemSound
-     * @param {} sound
-     * @param {} position
-     * @returns {object}
+     * @param {SoundObject} sound - TODO
+     * @param {Vec3} position - TODO
+     * @returns {AudioInjector} TODO
      */
     // FIXME: there is no way to play a positionless sound
     Q_INVOKABLE ScriptAudioInjector* playSystemSound(SharedSoundPointer sound, const QVector3D& position);
 
     /**jsdoc
+     * TODO
      * @function Audio.setStereoInput
-     * @param {boolean} stereo
+     * @param {boolean} stereo - TODO
      */
     Q_INVOKABLE void setStereoInput(bool stereo);
 
     /**jsdoc
+     * TODO
      * @function Audio.isStereoInput
-     * @returns {boolean} 
+     * @returns {boolean} <code>true</code> if TODO, otherwise <code>false</code>. 
      */
     Q_INVOKABLE bool isStereoInput();
 
 signals:
 
     /**jsdoc
-     * The client has been muted by the mixer.
+     * Triggered when the client is muted by the mixer.
      * @function Audio.mutedByMixer
      * @returns {Signal} 
      */
     void mutedByMixer();
 
     /**jsdoc
-     * The entire environment has been muted by the mixer.
+     * Triggered when the entire environment is muted by the mixer. TODO: What is the "whole environment"?
      * @function Audio.environmentMuted
      * @returns {Signal} 
      */
     void environmentMuted();
 
     /**jsdoc
-     * The client has received its first packet from the audio mixer.
+     * Triggered when the client receives its first packet from the audio mixer.
      * @function Audio.receivedFirstPacket
      * @returns {Signal} 
      */
     void receivedFirstPacket();
 
     /**jsdoc
-     * The client has been disconnected from the audio mixer.
+     * Triggered when the client is disconnected from the audio mixer.
      * @function Audio.disconnected
      * @returns {Signal} 
      */
     void disconnected();
 
     /**jsdoc
-     * The noise gate has opened.
+     * Triggered when the noise gate is opened. TODO: Description of noise gate.
      * @function Audio.noiseGateOpened
      * @returns {Signal} 
      */
     void noiseGateOpened();
 
     /**jsdoc
-     * The noise gate has closed.
+     * Triggered when the noise gate is closed. TODO: Description of noise gate.
      * @function Audio.noiseGateClosed
      * @returns {Signal} 
      */
     void noiseGateClosed();
 
     /**jsdoc
-     * A frame of mic input audio has been received and processed.
+     * Triggered when a frame of microphone audio input is processed.
      * @function Audio.inputReceived
-     * @param {} inputSamples
+     * @param {Int16Array} inputSamples - TODO
      * @returns {Signal} 
      */
     void inputReceived(const QByteArray& inputSamples);
 
     /**jsdoc
-    * @function Audio.isStereoInputChanged
-    * @param {boolean} isStereo
-    * @returns {Signal}
-    */
+     * TODO
+     * @function Audio.isStereoInputChanged
+     * @param {boolean} isStereo - TODO
+     * @returns {Signal}
+     */
     void isStereoInputChanged(bool isStereo);
 
 private:

libraries/script-engine/src/ScriptAudioInjector.h

@@ -16,6 +16,21 @@
 
 #include <AudioInjector.h>
 
+/**jsdoc
+ * TODO
+ * Used in the {@link Audio} API.
+ *
+ * @class AudioInjector
+ *
+ * @hifi-interface
+ * @hifi-client-entity
+ * @hifi-server-entity
+ * @hifi-assignment-client
+ *
+ * @property {boolean} playing - <code>true</code> if TODO, otherwise <code>false</code>. <em>Read-only.</em>
+ * @property {number} loudness - TODO <em>Read-only.</em>
+ * @property {AudioInjector.AudioInjectorOptions} options - TODO
+ */
 class ScriptAudioInjector : public QObject {
     Q_OBJECT
 
@@ -26,19 +41,62 @@ public:
     ScriptAudioInjector(const AudioInjectorPointer& injector);
     ~ScriptAudioInjector();
 public slots:
+
+    /**jsdoc
+     * TODO
+     * @function AudioInjector.restart
+     */
     void restart() { _injector->restart(); }
+
+    /**jsdoc
+     * TODO
+     * @function AudioInjector.stop
+     */
     void stop() { _injector->stop(); }
 
+    /**jsdoc
+     * TODO
+     * @function AudioInjector.getOptions
+     * @returns {AudioInjector.AudioInjectorOptions} TODO
+     */
     const AudioInjectorOptions& getOptions() const { return _injector->getOptions(); }
+
+    /**jsdoc
+     * TODO
+     * @function AudioInjector.setOptions
+     * @param {AudioInjector.AudioInjectorOptions} options - TODO
+     */
     void setOptions(const AudioInjectorOptions& options) { _injector->setOptions(options); }
 
+    /**jsdoc
+     * TODO
+     * @function AudioInjector.getLoudness
+     * @returns {number} TODO
+     */
     float getLoudness() const { return _injector->getLoudness(); }
+
+    /**jsdoc
+     * TODO
+     * @function AudioInjector.isPlaying
+     * @returns {boolean} <code>true</code> if TODO, otherwise <code>false</code>.
+     */
     bool isPlaying() const { return _injector->isPlaying(); }
 
 signals:
+
+    /**jsdoc
+     * Triggered when TODO
+     * @function AudioInjector.finished
+     * @returns {Signal}
+     */
     void finished();
 
 protected slots:
+
+    /**jsdoc
+     * TODO
+     * @function AudioInjector.stopInjectorImmediately
+     */
     void stopInjectorImmediately();
 private:
     AudioInjectorPointer _injector;