Controller JSDoc update

interface/src/Application.cpp

@@ -662,9 +662,10 @@ private:
 
 /**jsdoc
  * <p>The <code>Controller.Hardware.Application</code> object has properties representing Interface's state. The property
- * values are integer IDs, uniquely identifying each output. <em>Read-only.</em> These can be mapped to actions or functions or
+ * values are integer IDs, uniquely identifying each output. <em>Read-only.</em></p>
- * <code>Controller.Standard</code> items in a {@link RouteObject} mapping (e.g., using the {@link RouteObject#when} method).
+ * <p>These states can be mapped to actions or functions or <code>Controller.Standard</code> items in a {@link RouteObject} 
- * Each data value is either <code>1.0</code> for "true" or <code>0.0</code> for "false".</p>
+ * mapping (e.g., using the {@link RouteObject#when} method). Each data value is either <code>1.0</code> for "true" or 
+ * <code>0.0</code> for "false".</p>
  * <table>
  *   <thead>
  *     <tr><th>Property</th><th>Type</th><th>Data</th><th>Description</th></tr>
@@ -678,13 +679,17 @@ private:
  *     <tr><td><code>CameraIndependent</code></td><td>number</td><td>number</td><td>The camera is in independent mode.</td></tr>
  *     <tr><td><code>CameraEntity</code></td><td>number</td><td>number</td><td>The camera is in entity mode.</td></tr>
  *     <tr><td><code>InHMD</code></td><td>number</td><td>number</td><td>The user is in HMD mode.</td></tr>
- *     <tr><td><code>AdvancedMovement</code></td><td>number</td><td>number</td><td>Advanced movement controls are enabled.
+ *     <tr><td><code>AdvancedMovement</code></td><td>number</td><td>number</td><td>Advanced movement (walking) controls are 
- *       </td></tr>
+ *       enabled.</td></tr>
+ *     <tr><td><code>StrafeEnabled</code></td><td>number</td><td>number</td><td>Strafing is enabled</td></tr>
  *     <tr><td><code>LeftHandDominant</code></td><td>number</td><td>number</td><td>Dominant hand set to left.</td></tr>
  *     <tr><td><code>RightHandDominant</code></td><td>number</td><td>number</td><td>Dominant hand set to right.</td></tr>
  *     <tr><td><code>SnapTurn</code></td><td>number</td><td>number</td><td>Snap turn is enabled.</td></tr>
  *     <tr><td><code>Grounded</code></td><td>number</td><td>number</td><td>The user's avatar is on the ground.</td></tr>
  *     <tr><td><code>NavigationFocused</code></td><td>number</td><td>number</td><td><em>Not used.</em></td></tr>
+ *     <tr><td><code>PlatformWindows</code></td><td>number</td><td>number</td><td>The operating system is Windows.</td></tr>
+ *     <tr><td><code>PlatformMac</code></td><td>number</td><td>number</td><td>The operating system is Mac.</td></tr>
+ *     <tr><td><code>PlatformAndroid</code></td><td>number</td><td>number</td><td>The operating system is Android.</td></tr>
  *   </tbody>
  * </table>
  * @typedef {object} Controller.Hardware-Application

interface/src/scripting/ControllerScriptingInterface.h

@@ -26,9 +26,9 @@ class ScriptEngine;
 
 
 /**jsdoc
- * The Controller API provides facilities to interact with computer and controller hardware.
+ * The <code>Controller</code> API provides facilities to interact with computer and controller hardware.
  *
- * <h5>Functions</h5>
+ * <h4>Facilities</h4>
  *
  * <p>Properties</p>
  * <ul>
@@ -55,16 +55,18 @@ class ScriptEngine;
  *   <li>{@link Controller.getAvailableInputs|getAvailableInputs}</li>
  *   <li>{@link Controller.getDeviceName|getDeviceName}</li>
  *   <li>{@link Controller.getDeviceNames|getDeviceNames}</li>
+ *   <li>{@link Controller.getRunningInputDevices|getRunningInputDevices}</li>
  * </ul>
  *
- * <p>Input, Hardware, and Action Events</p>
+ * <p>Input, Hardware, and Action Signals</p>
  * <ul>
  *   <li>{@link Controller.actionEvent|actionEvent}</li>
  *   <li>{@link Controller.hardwareChanged|hardwareChanged}</li>
+ *   <li>{@link Controller.inputDeviceRunningChanged|inputDeviceRunningChanged}</li>
  *   <li>{@link Controller.inputEvent|inputEvent}</li>
  * </ul>
  *
- * <p>Mouse, Keyboard, and Touch Events</p>
+ * <p>Mouse, Keyboard, and Touch Signals</p>
  * <ul>
  *   <li>{@link Controller.keyPressEvent|keyPressEvent}</li>
  *   <li>{@link Controller.keyReleaseEvent|keyReleaseEvent}</li>
@@ -140,10 +142,10 @@ class ScriptEngine;
  *   <li>{@link Controller.stopInputPlayback|stopInputPlayback}</li>
  * </ul>
  *
- * <h5>Entity Methods:</h5>
+ * <h4>Entity Methods</h4>
  *
  * <p>The default scripts implement hand controller actions that use {@link Entities.callEntityMethod} to call entity script 
- * methods, if present in the entity being interacted with.</p>
+ * methods, if present, in the entity being interacted with.</p>
  *
  * <table>
  *   <thead>
@@ -203,7 +205,7 @@ class ScriptEngine;
  *
  * @property {Controller.Actions} Actions - Predefined actions on Interface and the user's avatar. These can be used as end
  *     points in a {@link RouteObject} mapping. A synonym for <code>Controller.Hardware.Actions</code>.
- *     <em>Read-only.</em><br />
+ *     <em>Read-only.</em><br /><br />
  *     Default mappings are provided from the <code>Controller.Hardware.Keyboard</code> and <code>Controller.Standard</code> to 
  *     actions in 
  *     <a href="https://github.com/highfidelity/hifi/blob/master/interface/resources/controllers/keyboardMouse.json">
@@ -217,7 +219,7 @@ class ScriptEngine;
  *     controller outputs. <em>Read-only.</em>
  *
  * @property {Controller.Standard} Standard - Standard controller outputs that can be mapped to <code>Actions</code> or 
- *     functions in a {@link RouteObject} mapping. <em>Read-only.</em><br />
+ *     functions in a {@link RouteObject} mapping. <em>Read-only.</em><br /><br />
  *     Each hardware device has a mapping from its outputs to <code>Controller.Standard</code> items, specified in a JSON file. 
  *     For example, <a href="https://github.com/highfidelity/hifi/blob/master/interface/resources/controllers/leapmotion.json">
  *     leapmotion.json</a> and 
@@ -253,7 +255,7 @@ public:
 public slots:
 
     /**jsdoc
-     * Disable default Interface actions for a particular key event.
+     * Disables default Interface actions for a particular key event.
      * @function Controller.captureKeyEvents
      * @param {KeyEvent} event - Details of the key event to be captured. The <code>key</code> property must be specified. The 
      *     <code>text</code> property is ignored. The other properties default to <code>false</code>.
@@ -272,7 +274,7 @@ public slots:
     virtual void captureKeyEvents(const KeyEvent& event);
 
     /**jsdoc
-     * Re-enable default Interface actions for a particular key event that has been disabled using 
+     * Re-enables default Interface actions for a particular key event that has been disabled using 
      * {@link Controller.captureKeyEvents|captureKeyEvents}.
      * @function Controller.releaseKeyEvents
      * @param {KeyEvent} event - Details of the key event to release from capture. The <code>key</code> property must be 
@@ -281,7 +283,7 @@ public slots:
     virtual void releaseKeyEvents(const KeyEvent& event);
 
     /**jsdoc
-     * Disable default Interface actions for a joystick.
+     * Disables default Interface actions for a joystick.
      * @function Controller.captureJoystick
      * @param {number} joystickID - The integer ID of the joystick.
      * @deprecated This function no longer has any effect.
@@ -289,7 +291,7 @@ public slots:
     virtual void captureJoystick(int joystickIndex);
 
     /**jsdoc
-     * Re-enable default Interface actions for a joystick that has been disabled using 
+     * Re-enables default Interface actions for a joystick that has been disabled using 
      * {@link Controller.captureJoystick|captureJoystick}.
      * @function Controller.releaseJoystick
      * @param {number} joystickID - The integer ID of the joystick.
@@ -298,7 +300,7 @@ public slots:
     virtual void releaseJoystick(int joystickIndex);
 
     /**jsdoc
-     * Disable {@link Entities.mousePressOnEntity} and {@link Entities.mouseDoublePressOnEntity} events on entities.
+     * Disables {@link Entities.mousePressOnEntity} and {@link Entities.mouseDoublePressOnEntity} events on entities.
      * @function Controller.captureEntityClickEvents
      * @example <caption>Disable entity click events for a short period.</caption>
      * Entities.mousePressOnEntity.connect(function (entityID, event) {
@@ -316,7 +318,7 @@ public slots:
     virtual void captureEntityClickEvents();
 
     /**jsdoc
-     * Re-enable {@link Entities.mousePressOnEntity} and {@link Entities.mouseDoublePressOnEntity} events on entities that were 
+     * Re-enables {@link Entities.mousePressOnEntity} and {@link Entities.mouseDoublePressOnEntity} events on entities that were 
      * disabled using {@link Controller.captureEntityClickEvents|captureEntityClickEvents}.
      * @function Controller.releaseEntityClickEvents
      */
@@ -324,14 +326,14 @@ public slots:
 
 
     /**jsdoc
-     * Get the dimensions of the Interface window's interior if in desktop mode or the HUD surface if in HMD mode.
+     * Gets the dimensions of the Interface window's interior if in desktop mode or the HUD surface if in HMD mode.
      * @function Controller.getViewportDimensions
      * @returns {Vec2} The dimensions of the Interface window interior if in desktop mode or HUD surface if in HMD mode.
      */
     virtual glm::vec2 getViewportDimensions() const;
 
     /**jsdoc
-     * Get the recommended area to position UI on the HUD surface if in HMD mode or Interface's window interior if in desktop 
+     * Gets the recommended area to position UI on the HUD surface if in HMD mode or Interface's window interior if in desktop 
      * mode.
      * @function Controller.getRecommendedHUDRect
      * @returns {Rect} The recommended area in which to position UI.

libraries/controllers/src/controllers/Actions.cpp

@@ -35,9 +35,9 @@ namespace controller {
 
     /**jsdoc
      * <p>The <code>Controller.Actions</code> object has properties representing predefined actions on the user's avatar and 
-     * Interface. The property values are integer IDs, uniquely identifying each action. <em>Read-only.</em> These can be used 
+     * Interface. The property values are integer IDs, uniquely identifying each action. <em>Read-only.</em></p>
-     * as end points in the routes of a {@link MappingObject}. The data routed to each action is either a number or a 
+     * <p>These actions can be used as end points in the routes of a {@link MappingObject}. The data item routed to each action 
-     * {@link Pose}.</p>
+     * is either a number or a {@link Pose}.</p>
      *
      * <table>
      *   <thead>
@@ -246,8 +246,6 @@ namespace controller {
      *       <code>ContextMenu</code> instead.</td></tr>
      *     <tr><td><code>TOGGLE_MUTE</code></td><td>number</td><td>number</td><td><strong>Deprecated:</strong> Use 
      *       <code>ToggleMute</code> instead.</td></tr>
-     *     <tr><td><code>TOGGLE_PUSHTOTALK</code></td><td>number</td><td>number</td><td><strong>Deprecated:</strong> Use 
-     *       <code>TogglePushToTalk</code> instead.</td></tr>
      *     <tr><td><code>SPRINT</code></td><td>number</td><td>number</td><td><strong>Deprecated:</strong> Use 
      *       <code>Sprint</code> instead.</td></tr>
      *     <tr><td><code>LONGITUDINAL_BACKWARD</code></td><td>number</td><td>number</td><td><strong>Deprecated:</strong> Use 

libraries/controllers/src/controllers/InputDevice.h

@@ -54,10 +54,9 @@ enum Hand {
 
 /**jsdoc
  * <p>The <code>Controller.Hardware</code> object has properties representing standard and hardware-specific controller and 
- * computer outputs, plus predefined actions on Interface and the user's avatar. <em>Read-only.</em> The outputs can be mapped 
+ * computer outputs, plus predefined actions on Interface and the user's avatar. <em>Read-only.</em></p>
- * to actions or functions in a {@link RouteObject} mapping. Additionally, hardware-specific controller outputs can be mapped 
+ * <p>The outputs can be mapped to actions or functions in a {@link RouteObject} mapping. Additionally, hardware-specific 
- * to standard controller outputs. 
+ * controller outputs can be mapped to standard controller outputs. 
- * 
  * <p>Controllers typically implement a subset of the {@link Controller.Standard} controls, plus they may implement some extras. 
  * Some common controllers are included in the table. You can see the outputs provided by these and others by 
  * viewing their {@link Controller.MappingJSON|MappingJSON} files at 

libraries/controllers/src/controllers/ScriptingInterface.cpp

@@ -227,6 +227,7 @@ namespace controller {
     }
 
     QObject* ScriptingInterface::loadMapping(const QString& jsonUrl) {
+        // FIXME: Implement. https://highfidelity.manuscript.com/f/cases/14188/Implement-Controller-loadMappping
         return nullptr;
     }
 

libraries/controllers/src/controllers/ScriptingInterface.h

@@ -73,7 +73,7 @@ namespace controller {
         virtual ~ScriptingInterface() {};
 
         /**jsdoc
-         * Get a list of all available actions.
+         * Gets a list of all available actions.
          * @function Controller.getAllActions
          * @returns {Action[]} All available actions.
          * @deprecated This function no longer works.
@@ -82,7 +82,7 @@ namespace controller {
         Q_INVOKABLE QVector<Action> getAllActions();
         
         /**jsdoc
-         * Get a list of all available inputs for a hardware device.
+         * Gets a list of all available inputs for a hardware device.
          * @function Controller.getAvailableInputs
          * @param {number} deviceID - Integer ID of the hardware device.
          * @returns {NamedPair[]} All available inputs for the device.
@@ -92,7 +92,7 @@ namespace controller {
         Q_INVOKABLE QVector<Input::NamedPair> getAvailableInputs(unsigned int device);
         
         /**jsdoc
-         * Find the name of a particular controller from its device ID.
+         * Finds the name of a particular controller from its device ID.
          * @function Controller.getDeviceName
          * @param {number} deviceID - The integer ID of the device.
          * @returns {string} The name of the device if found, otherwise <code>"unknown"</code>.
@@ -106,7 +106,7 @@ namespace controller {
         Q_INVOKABLE QString getDeviceName(unsigned int device);
 
         /**jsdoc
-         * Get the current value of an action.
+         * Gets the current value of an action.
          * @function Controller.getActionValue
          * @param {number} actionID - The integer ID of the action.
          * @returns {number} The current value of the action.
@@ -121,7 +121,7 @@ namespace controller {
         Q_INVOKABLE float getActionValue(int action);
 
         /**jsdoc
-         * Find the ID of a specific controller from its device name.
+         * Finds the ID of a specific controller from its device name.
          * @function Controller.findDevice
          * @param {string} deviceName - The name of the device to find.
          * @returns {number} The integer ID of the device if available, otherwise <code>65535</code>.
@@ -132,7 +132,7 @@ namespace controller {
         Q_INVOKABLE int findDevice(QString name);
 
         /**jsdoc
-         * Get the names of all currently available controller devices plus "Actions", "Application", and "Standard".
+         * Gets the names of all currently available controller devices plus "Actions", "Application", and "Standard".
          * @function Controller.getDeviceNames
          * @returns {string[]} An array of device names.
          * @example <caption>Get the names of all currently available controller devices.</caption>
@@ -143,7 +143,7 @@ namespace controller {
         Q_INVOKABLE QVector<QString> getDeviceNames();
         
         /**jsdoc
-         * Find the ID of an action from its name.
+         * Finds the ID of an action from its name.
          * @function Controller.findAction
          * @param {string} actionName - The name of the action: one of the {@link Controller.Actions} property names.
          * @returns {number} The integer ID of the action if found, otherwise <code>4095</code>. Note that this value is not 
@@ -156,7 +156,7 @@ namespace controller {
         Q_INVOKABLE int findAction(QString actionName);
 
         /**jsdoc
-         * Get the names of all actions available as properties of {@link Controller.Actions}.
+         * Gets the names of all actions available as properties of {@link Controller.Actions}.
          * @function Controller.getActionNames
          * @returns {string[]} An array of action names.
          * @example <caption>Get the names of all actions.</caption>
@@ -167,7 +167,7 @@ namespace controller {
         Q_INVOKABLE QVector<QString> getActionNames() const;
 
         /**jsdoc
-         * Get the value of a controller button or axis output. Note: Also gets the value of a controller axis output. 
+         * Gets the value of a controller button or axis output. Note: Also gets the value of a controller axis output. 
          * @function Controller.getValue
          * @param {number} source - The {@link Controller.Standard} or {@link Controller.Hardware} item.
          * @returns {number} The current value of the controller item output if <code>source</code> is valid, otherwise 
@@ -186,7 +186,7 @@ namespace controller {
         Q_INVOKABLE float getValue(const int& source) const;
 
         /**jsdoc
-         * Get the value of a controller axis output. Note: Also gets the value of a controller button output.
+         * Gets the value of a controller axis output. Note: Also gets the value of a controller button output.
          * @function Controller.getAxisValue
          * @param {number} source - The {@link Controller.Standard} or {@link Controller.Hardware} item.
          * @returns {number} The current value of the controller item output if <code>source</code> is valid, otherwise 
@@ -196,7 +196,7 @@ namespace controller {
         Q_INVOKABLE float getAxisValue(int source) const;
 
         /**jsdoc
-         * Get the value of a controller pose output.
+         * Gets the value of a controller pose output.
          * @function Controller.getPoseValue
          * @param {number} source - The {@link Controller.Standard} or {@link Controller.Hardware} pose output.
          * @returns {Pose} The current value of the controller pose output if <code>source</code> is a pose output, otherwise 
@@ -212,7 +212,7 @@ namespace controller {
          * @function Controller.triggerHapticPulse
          * @param {number} strength - The strength of the haptic pulse, <code>0.0</code> &ndash; <code>1.0</code>.
          * @param {number} duration - The duration of the haptic pulse, in milliseconds.
-         * @param {Controller.Hand} hand=2 - The hand or hands to trigger the haptic pulse on.
+         * @param {Controller.Hand} [hand=2] - The hand or hands to trigger the haptic pulse on.
          * @example <caption>Trigger a haptic pulse on the right hand.</caption>
          * var HAPTIC_STRENGTH = 0.5;
          * var HAPTIC_DURATION = 10;
@@ -225,7 +225,7 @@ namespace controller {
          * Triggers a 250ms haptic pulse on connected and enabled devices that have the capability.
          * @function Controller.triggerShortHapticPulse
          * @param {number} strength - The strength of the haptic pulse, <code>0.0</code> &ndash; <code>1.0</code>.
-         * @param {Controller.Hand} hand=2 - The hand or hands to trigger the haptic pulse on.
+         * @param {Controller.Hand} [hand=2] - The hand or hands to trigger the haptic pulse on.
          */
         Q_INVOKABLE bool triggerShortHapticPulse(float strength, controller::Hand hand = BOTH) const;
 
@@ -235,7 +235,7 @@ namespace controller {
          * @param {number} deviceID - The ID of the device to trigger the haptic pulse on.
          * @param {number} strength - The strength of the haptic pulse, <code>0.0</code> &ndash; <code>1.0</code>.
          * @param {number} duration - The duration of the haptic pulse, in milliseconds.
-         * @param {Controller.Hand} hand=2 - The hand or hands to trigger the haptic pulse on.
+         * @param {Controller.Hand} [hand=2] - The hand or hands to trigger the haptic pulse on.
          * @example <caption>Trigger a haptic pulse on an Oculus Touch controller.</caption>
          * var HAPTIC_STRENGTH = 0.5;
          * var deviceID = Controller.findDevice("OculusTouch");
@@ -251,18 +251,18 @@ namespace controller {
          * @function Controller.triggerShortHapticPulseOnDevice
          * @param {number} deviceID - The ID of the device to trigger the haptic pulse on.
          * @param {number} strength - The strength of the haptic pulse, <code>0.0</code> &ndash; <code>1.0</code>.
-         * @param {Controller.Hand} hand=2 - The hand or hands to trigger the haptic pulse on.
+         * @param {Controller.Hand} [hand=2] - The hand or hands to trigger the haptic pulse on.
          */
         Q_INVOKABLE bool triggerShortHapticPulseOnDevice(unsigned int device, float strength, controller::Hand hand = BOTH) 
             const;
 
 
         /**jsdoc
-         * Create a new controller mapping. Routes can then be added to the mapping using {@link MappingObject} methods and 
+         * Creates a new controller mapping. Routes can then be added to the mapping using {@link MappingObject} methods and 
          * routed to <code>Standard</code> controls, <code>Actions</code>, or script functions using {@link RouteObject} 
          * methods. The mapping can then be enabled using {@link Controller.enableMapping|enableMapping} for it to take effect.
          * @function Controller.newMapping
-         * @param {string} mappingName=Uuid.generate() - A unique name for the mapping. If not specified a new UUID generated 
+         * @param {string} [mappingName=Uuid.generate()] - A unique name for the mapping. If not specified a new UUID generated 
          *     by {@link Uuid.generate} is used.
          * @returns {MappingObject} A controller mapping object.
          * @example <caption>Create a simple mapping that makes the right trigger move your avatar up.</caption>
@@ -279,22 +279,22 @@ namespace controller {
         Q_INVOKABLE QObject* newMapping(const QString& mappingName = QUuid::createUuid().toString());
 
         /**jsdoc
-         * Enable or disable a controller mapping. When enabled, the routes in the mapping have effect.
+         * Enables or disables a controller mapping. When enabled, the routes in the mapping have effect.
          * @function Controller.enableMapping
          * @param {string} mappingName - The name of the mapping.
-         * @param {boolean} enable=true - If <code>true</code> then the mapping is enabled, otherwise it is disabled.
+         * @param {boolean} [[enable=true] - If <code>true</code> then the mapping is enabled, otherwise it is disabled.
          */
         Q_INVOKABLE void enableMapping(const QString& mappingName, bool enable = true);
 
         /**jsdoc
-         * Disable a controller mapping. When disabled, the routes in the mapping have no effect.
+         * Disables a controller mapping. When disabled, the routes in the mapping have no effect.
          * @function Controller.disableMapping
          * @param {string} mappingName - The name of the mapping.
          */
         Q_INVOKABLE void disableMapping(const QString& mappingName) { enableMapping(mappingName, false); }
 
         /**jsdoc
-         * Create a new controller mapping from a {@link Controller.MappingJSON|MappingJSON} string. Use 
+         * Creates a new controller mapping from a {@link Controller.MappingJSON|MappingJSON} string. Use 
          * {@link Controller.enableMapping|enableMapping} to enable the mapping for it to take effect.
          * @function Controller.parseMapping
          * @param {string} jsonString - A JSON string of the {@link Controller.MappingJSON|MappingJSON}.
@@ -317,19 +317,19 @@ namespace controller {
         Q_INVOKABLE QObject* parseMapping(const QString& json);
 
         /**jsdoc
-         * Create a new controller mapping from a {@link Controller.MappingJSON|MappingJSON} JSON file at a URL. Use 
+         * Creates a new controller mapping from a {@link Controller.MappingJSON|MappingJSON} JSON file at a URL. Use 
          * {@link Controller.enableMapping|enableMapping} to enable the mapping for it to take effect.
+         * <p><strong>Warning:</strong> This function is not yet implemented; it doesn't load a mapping and just returns 
+         * <code>null</code>.
          * @function Controller.loadMapping
          * @param {string} jsonURL - The URL the {@link Controller.MappingJSON|MappingJSON} JSON file.
          * @returns {MappingObject} A controller mapping object.
-         * @todo <em>Implement this function. It currently does not load the mapping from the file; it just returns 
-         *     <code>null</code>.</em>
          */
         Q_INVOKABLE QObject* loadMapping(const QString& jsonUrl);
 
 
         /**jsdoc
-         * Get the {@link Controller.Hardware} property tree. Calling this function is the same as using the {@link Controller} 
+         * Gets the {@link Controller.Hardware} property tree. Calling this function is the same as using the {@link Controller} 
          * property, <code>Controller.Hardware</code>.
          * @function Controller.getHardware
          * @returns {Controller.Hardware} The {@link Controller.Hardware} property tree.
@@ -337,7 +337,7 @@ namespace controller {
         Q_INVOKABLE const QVariantMap getHardware() { return _hardware; }
 
         /**jsdoc
-         * Get the {@link Controller.Actions} property tree. Calling this function is the same as using the {@link Controller} 
+         * Gets the {@link Controller.Actions} property tree. Calling this function is the same as using the {@link Controller} 
          * property, <code>Controller.Actions</code>.
          * @function Controller.getActions
          * @returns {Controller.Actions} The {@link Controller.Actions} property tree.
@@ -345,7 +345,7 @@ namespace controller {
         Q_INVOKABLE const QVariantMap getActions() { return _actions; }  //undefined
 
         /**jsdoc
-         * Get the {@link Controller.Standard} property tree. Calling this function is the same as using the {@link Controller} 
+         * Gets the {@link Controller.Standard} property tree. Calling this function is the same as using the {@link Controller} 
          * property, <code>Controller.Standard</code>.
          * @function Controller.getStandard
          * @returns {Controller.Standard} The {@link Controller.Standard} property tree.
@@ -354,7 +354,7 @@ namespace controller {
 
 
         /**jsdoc
-         * Start making a recording of currently active controllers.
+         * Starts making a recording of currently active controllers.
          * @function Controller.startInputRecording
          * @example <caption>Make a controller recording.</caption>
          * // Delay start of recording for 2s.
@@ -374,13 +374,13 @@ namespace controller {
         Q_INVOKABLE void startInputRecording();
 
         /**jsdoc
-         * Stop making a recording started by {@link Controller.startInputRecording|startInputRecording}.
+         * Stops making a recording started by {@link Controller.startInputRecording|startInputRecording}.
          * @function Controller.stopInputRecording
          */
         Q_INVOKABLE void stopInputRecording();
 
         /**jsdoc
-         * Play back the current recording from the beginning. The current recording may have been recorded by 
+         * Plays back the current recording from the beginning. The current recording may have been recorded by 
          * {@link Controller.startInputRecording|startInputRecording} and 
          * {@link Controller.stopInputRecording|stopInputRecording}, or loaded by 
          * {@link Controller.loadInputRecording|loadInputRecording}. Playback repeats in a loop until 
@@ -403,13 +403,13 @@ namespace controller {
         Q_INVOKABLE void startInputPlayback();
 
         /**jsdoc
-         * Stop play back of a recording started by {@link Controller.startInputPlayback|startInputPlayback}.
+         * Stops play back of a recording started by {@link Controller.startInputPlayback|startInputPlayback}.
          * @function Controller.stopInputPlayback
          */
         Q_INVOKABLE void stopInputPlayback();
 
         /**jsdoc
-         * Save the current recording to a file. The current recording may have been recorded by
+         * Saves the current recording to a file. The current recording may have been recorded by
          * {@link Controller.startInputRecording|startInputRecording} and
          * {@link Controller.stopInputRecording|stopInputRecording}, or loaded by
          * {@link Controller.loadInputRecording|loadInputRecording}. It is saved in the directory returned by 
@@ -419,24 +419,26 @@ namespace controller {
         Q_INVOKABLE void saveInputRecording();
 
         /**jsdoc
-         * Load an input recording, ready for play back.
+         * Loads an input recording, ready for play back.
          * @function Controller.loadInputRecording
          * @param {string} file - The path to the recording file, prefixed by <code>"file:///"</code>.
          */
         Q_INVOKABLE void loadInputRecording(const QString& file);
 
         /**jsdoc
-         * Get the directory in which input recordings are saved.
+         * Gets the directory in which input recordings are saved.
          * @function Controller.getInputRecorderSaveDirectory
          * @returns {string} The directory in which input recordings are saved.
          */
         Q_INVOKABLE QString getInputRecorderSaveDirectory();
 
         /**jsdoc
-        * Get all the active and enabled (running) input devices
+         * Gets the names of all the active and running (enabled) input devices.
-        * @function Controller.getRunningInputDevices
+         * @function Controller.getRunningInputDevices
-        * @returns {string[]} An array of strings with the names
+         * @returns {string[]} The list of current active and running input devices.
-        */
+         * @example <caption>List all active and running input devices.</caption>
+         * print("Running devices: " + JSON.stringify(Controller.getRunningInputDeviceNames()));
+         */
         Q_INVOKABLE QStringList getRunningInputDeviceNames();
 
         bool isMouseCaptured() const { return _mouseCaptured; }
@@ -447,7 +449,7 @@ namespace controller {
     public slots:
 
         /**jsdoc
-         * Disable processing of mouse "move", "press", "double-press", and "release" events into 
+         * Disables processing of mouse "move", "press", "double-press", and "release" events into 
          * {@link Controller.Hardware|Controller.Hardware.Keyboard} outputs.
          * @function Controller.captureMouseEvents
          * @example <caption>Disable Controller.Hardware.Keyboard mouse events for a short period.</caption>
@@ -475,7 +477,7 @@ namespace controller {
         virtual void captureMouseEvents() { _mouseCaptured = true; }
 
         /**jsdoc
-         * Enable processing of mouse "move", "press", "double-press", and "release" events into 
+         * Enables processing of mouse "move", "press", "double-press", and "release" events into 
          * {@link Controller.Hardware-Keyboard|Controller.Hardware.Keyboard} outputs that were disabled using 
          * {@link Controller.captureMouseEvents|captureMouseEvents}.
          * @function Controller.releaseMouseEvents
@@ -484,7 +486,7 @@ namespace controller {
 
 
         /**jsdoc
-         * Disable processing of touch "begin", "update", and "end" events into 
+         * Disables processing of touch "begin", "update", and "end" events into 
          * {@link Controller.Hardware|Controller.Hardware.Keyboard}, 
          * {@link Controller.Hardware|Controller.Hardware.Touchscreen}, and 
          * {@link Controller.Hardware|Controller.Hardware.TouchscreenVirtualPad} outputs.
@@ -493,7 +495,7 @@ namespace controller {
         virtual void captureTouchEvents() { _touchCaptured = true; }
 
         /**jsdoc
-         * Enable processing of touch "begin", "update", and "end" events into 
+         * Enables processing of touch "begin", "update", and "end" events into 
          * {@link Controller.Hardware|Controller.Hardware.Keyboard}, 
          * {@link Controller.Hardware|Controller.Hardware.Touchscreen}, and 
          * {@link Controller.Hardware|Controller.Hardware.TouchscreenVirtualPad} outputs that were disabled using 
@@ -504,14 +506,14 @@ namespace controller {
 
 
         /**jsdoc
-         * Disable processing of mouse wheel rotation events into {@link Controller.Hardware|Controller.Hardware.Keyboard} 
+         * Disables processing of mouse wheel rotation events into {@link Controller.Hardware|Controller.Hardware.Keyboard} 
          * outputs.
          * @function Controller.captureWheelEvents
          */
         virtual void captureWheelEvents() { _wheelCaptured = true; }
 
         /**jsdoc
-         * Enable processing of mouse wheel rotation events into {@link Controller.Hardware|Controller.Hardware.Keyboard} 
+         * Enables processing of mouse wheel rotation events into {@link Controller.Hardware|Controller.Hardware.Keyboard} 
          * outputs that wer disabled using {@link Controller.captureWheelEvents|captureWheelEvents}.
          * @function Controller.releaseWheelEvents
          */
@@ -519,7 +521,7 @@ namespace controller {
 
 
         /**jsdoc
-         * Disable translating and rotating the user's avatar in response to keyboard and controller controls.
+         * Disables translating and rotating the user's avatar in response to keyboard and controller controls.
          * @function Controller.captureActionEvents
          * @example <caption>Disable avatar translation and rotation for a short period.</caption>
          * Script.setTimeout(function () {
@@ -533,12 +535,19 @@ namespace controller {
         virtual void captureActionEvents() { _actionsCaptured = true; }
 
         /**jsdoc
-         * Enable translating and rotating the user's avatar in response to keyboard and controller controls that were disabled 
+         * Enables translating and rotating the user's avatar in response to keyboard and controller controls that were disabled 
          * using {@link Controller.captureActionEvents|captureActionEvents}.
          * @function Controller.releaseActionEvents
          */
         virtual void releaseActionEvents() { _actionsCaptured = false; }
 
+        /**jsdoc
+         * @function Controller.updateRunningInputDevices
+         * @param {string} deviceName - Device name.
+         * @param {boolean} isRunning - Is running.
+         * @param {string[]} runningDevices - Running devices.
+         * @deprecated This function is deprecated and will be removed.
+         */
         void updateRunningInputDevices(const QString& deviceName, bool isRunning, const QStringList& runningDevices);
 
     signals:
@@ -593,7 +602,7 @@ namespace controller {
 
         /**jsdoc
          * Triggered when a device is registered or unregistered by a plugin. Not all plugins generate 
-         * <code>hardwareChanged</code> events: for example connecting or disconnecting a mouse will not generate an event but 
+         * <code>hardwareChanged</code> events: for example, connecting or disconnecting a mouse will not generate an event but 
          * connecting or disconnecting an Xbox controller will.
          * @function Controller.hardwareChanged
          * @returns {Signal}
@@ -601,13 +610,13 @@ namespace controller {
         void hardwareChanged();
 
         /**jsdoc
-        * Triggered when a device is enabled/disabled
+         * Triggered when an input device starts or stops being active and running (enabled). For example, enabling or 
-        * Enabling/Disabling Leapmotion on settings/controls will trigger this signal.
+         * disabling the LeapMotion in Settings &gt; Controls &gt; Calibration will trigger this signal.
-        * @function Controller.deviceRunningChanged
+         * @function Controller.inputDeviceRunningChanged
-        * @param {string} deviceName - The name of the device that is getting enabled/disabled
+         * @param {string} deviceName - The name of the device.
-        * @param {boolean} isEnabled - Return if the device is enabled.
+         * @param {boolean} isRunning - <code>true</code> if the device is active and running, <code>false</code> if it isn't.
-        * @returns {Signal}
+         * @returns {Signal}
-        */
+         */
         void inputDeviceRunningChanged(QString deviceName, bool isRunning);
 
 

libraries/controllers/src/controllers/StandardController.cpp

@@ -30,17 +30,16 @@ void StandardController::focusOutEvent() {
 /**jsdoc
  * <p>The <code>Controller.Standard</code> object has properties representing standard controller outputs. Those for physical 
  * controllers are based on the XBox controller, with aliases for PlayStation. The property values are integer IDs, uniquely 
- * identifying each output. <em>Read-only.</em> These can be mapped to actions or functions in a {@link RouteObject} 
+ * identifying each output. <em>Read-only.</em></p>
- * mapping.</p>
+ * <p>These outputs can be mapped to actions or functions in a {@link RouteObject} mapping. The data value provided by each 
- *
+ * control is either a number or a {@link Pose}. Numbers are typically normalized to <code>0.0</code> or <code>1.0</code> for 
- * <p>The data value provided by each control is either a number or a {@link Pose}. Numbers are typically normalized to
+ * button states, the range <code>0.0 &ndash; 1.0</code> for unidirectional scales, and the range <code>-1.0 &ndash; 1.0</code> 
- * <code>0.0</code> or <code>1.0</code> for button states, the range <code>0.0 &ndash; 1.0</code> for unidirectional scales,
+ * for bidirectional scales.</p>
- * and the range <code>-1.0 &ndash; 1.0</code> for bidirectional scales.</p>
+ * <p>Each hardware device has a mapping from its outputs to a subset of <code>Controller.Standard</code> items, specified in a 
- *
+ * JSON file. For example, 
- * <p>Each hardware device has a mapping from its outputs to <code>Controller.Standard</code> items, specified in a JSON file.
+ * <a href="https://github.com/highfidelity/hifi/blob/master/interface/resources/controllers/vive.json">vive.json</a>
- * For example, <a href="https://github.com/highfidelity/hifi/blob/master/interface/resources/controllers/leapmotion.json">
+ * and <a href="https://github.com/highfidelity/hifi/blob/master/interface/resources/controllers/leapmotion.json">
- * leapmotion.json</a> and
+ * leapmotion.json</a>.</p>
- * <a href="https://github.com/highfidelity/hifi/blob/master/interface/resources/controllers/vive.json">vive.json</a>.</p>
  *
  * <table>
  *   <thead>
@@ -119,12 +118,12 @@ void StandardController::focusOutEvent() {
  *       button.</td></tr>
  *     <tr><td><code>RightThumbUp</code></td><td>number</td><td>number</td><td>Right thumb not touching primary or secondary 
  *       thumb buttons.</td></tr>
- *     <tr><td><code>LeftPrimaryIndex</code></td><td>number</td><td>number</td><td>Left primary index control pressed. 
+ *     <tr><td><code>LeftPrimaryIndex</code></td><td>number</td><td>number</td><td>Left primary index control 
- *       <strong>To Do:</strong> <em>Implement this for current controllers.</em></td></tr>
+ *       pressed.</em></td></tr>
  *     <tr><td><code>LeftSecondaryIndex</code></td><td>number</td><td>number</td><td>Left secondary index control pressed.
  *       </td></tr>
  *     <tr><td><code>RightPrimaryIndex</code></td><td>number</td><td>number</td><td>Right primary index control pressed. 
- *       <strong>To Do:</strong> <em>Implement this for current controllers.</em></td></tr>
+ *       </td></tr>
  *     <tr><td><code>RightSecondaryIndex</code></td><td>number</td><td>number</td><td>Right secondary index control pressed.
  *       </td></tr>
  *     <tr><td><code>LeftPrimaryIndexTouch</code></td><td>number</td><td>number</td><td>Left index finger is touching primary 

libraries/controllers/src/controllers/impl/MappingBuilderProxy.h

@@ -134,7 +134,7 @@ public:
         : _parent(parent), _mapping(mapping) { }
 
     /**jsdoc
-     * Create a new {@link RouteObject} from a controller output, ready to be mapped to a standard control, action, or 
+     * Creates a new {@link RouteObject} from a controller output, ready to be mapped to a standard control, action, or 
      * function.<br />
      * This is a QML-specific version of {@link MappingObject#from|from}: use this version in QML files.
      * @function MappingObject#fromQml
@@ -145,7 +145,7 @@ public:
     Q_INVOKABLE QObject* fromQml(const QJSValue& source);
 
     /**jsdoc
-     * Create a new {@link RouteObject} from two numeric {@link Controller.Hardware} outputs, one applied in the negative 
+     * Creates a new {@link RouteObject} from two numeric {@link Controller.Hardware} outputs, one applied in the negative 
      * direction and the other in the positive direction, ready to be mapped to a standard control, action, or function.<br />
      * This is a QML-specific version of {@link MappingObject#makeAxis|makeAxis}: use this version in QML files.
      * @function MappingObject#makeAxisQml
@@ -157,7 +157,7 @@ public:
     Q_INVOKABLE QObject* makeAxisQml(const QJSValue& source1, const QJSValue& source2);
 
     /**jsdoc
-     * Create a new {@link RouteObject} from a controller output, ready to be mapped to a standard control, action, or 
+     * Creates a new {@link RouteObject} from a controller output, ready to be mapped to a standard control, action, or 
      * function.
      * @function MappingObject#from
      * @param {Controller.Standard|Controller.Hardware|function} source - The controller output or function that is the source 
@@ -167,7 +167,7 @@ public:
     Q_INVOKABLE QObject* from(const QScriptValue& source);
 
     /**jsdoc
-     * Create a new {@link RouteObject} from two numeric {@link Controller.Hardware} outputs, one applied in the negative 
+     * Creates a new {@link RouteObject} from two numeric {@link Controller.Hardware} outputs, one applied in the negative 
      * direction and the other in the positive direction, ready to be mapped to a standard control, action, or function.
      * @function MappingObject#makeAxis
      * @param {Controller.Hardware} source1 - The first, negative-direction controller output.
@@ -189,7 +189,7 @@ public:
     Q_INVOKABLE QObject* makeAxis(const QScriptValue& source1, const QScriptValue& source2);
 
     /**jsdoc
-     * Enable or disable the mapping. When enabled, the routes in the mapping take effect.<br />
+     * Enables or disables the mapping. When enabled, the routes in the mapping take effect.<br />
      * Synonymous with {@link Controller.enableMapping}.
      * @function MappingObject#enable
      * @param {boolean} enable=true - If <code>true</code> then the mapping is enabled, otherwise it is disabled.
@@ -198,7 +198,7 @@ public:
     Q_INVOKABLE QObject* enable(bool enable = true);
 
     /**jsdoc
-     * Disable the mapping. When disabled, the routes in the mapping have no effect.<br />
+     * Disables the mapping. When disabled, the routes in the mapping have no effect.<br />
      * Synonymous with {@link Controller.disableMapping}.
      * @function MappingObject#disable
      * @returns {MappingObject} The mapping object, so that further routes can be added.

libraries/controllers/src/controllers/impl/RouteBuilderProxy.cpp

@@ -66,6 +66,8 @@ QObject* RouteBuilderProxy::peek(bool enable) {
 }
 
 QObject* RouteBuilderProxy::when(const QScriptValue& expression) {
+    // FIXME: Support "!" conditional in simple expression and array expression.
+    // Note that "!" is supported when parsing a JSON file, in UserInputMapper::parseConditional().
     auto newConditional = _parent.conditionalFor(expression);
     if (_route->conditional) {
         _route->conditional = ConditionalPointer(new AndConditional(_route->conditional, newConditional));

libraries/controllers/src/controllers/impl/RouteBuilderProxy.h

@@ -51,7 +51,7 @@ class RouteBuilderProxy : public QObject {
             : _parent(parent), _mapping(mapping), _route(route) { }
 
         /**jsdoc
-         * Terminate the route with a standard control, an action, or a script function. The output value from the route is 
+         * Terminates the route with a standard control, an action, or a script function. The output value from the route is 
          * sent to the specified destination.<br />
          * This is a QML-specific version of {@link MappingObject#to|to}: use this version in QML files.
          * @function RouteObject#toQml
@@ -62,7 +62,7 @@ class RouteBuilderProxy : public QObject {
         Q_INVOKABLE void toQml(const QJSValue& destination);
 
         /**jsdoc
-         * Process the route only if a condition is satisfied. The condition is evaluated before the route input is read, and
+         * Processes the route only if a condition is satisfied. The condition is evaluated before the route input is read, and
          * the input is read only if the condition is <code>true</code>. Thus, if the condition is not met then subsequent
          * routes using the same input are processed.<br />
          * This is a QML-specific version of {@link MappingObject#to|to}: use this version in QML files.
@@ -81,7 +81,7 @@ class RouteBuilderProxy : public QObject {
         Q_INVOKABLE QObject* whenQml(const QJSValue& expression);
 
         /**jsdoc
-         * Terminate the route with a standard control, an action, or a script function. The output value from the route is 
+         * Terminates the route with a standard control, an action, or a script function. The output value from the route is 
          * sent to the specified destination.
          * @function RouteObject#to
          * @param {Controller.Standard|Controller.Actions|function} destination - The standard control, action, or JavaScript 
@@ -117,7 +117,7 @@ class RouteBuilderProxy : public QObject {
         Q_INVOKABLE void to(const QScriptValue& destination);
 
         /**jsdoc
-         * Enable and disabling writing debug information for a route to the program log.
+         * Enables or disables writing debug information for a route to the program log.
          * @function RouteObject#debug
          * @param {boolean} [enable=true] - If <code>true</code> then writing debug information is enabled for the route, 
          *     otherwise it is disabled.
@@ -147,7 +147,7 @@ class RouteBuilderProxy : public QObject {
         Q_INVOKABLE QObject* debug(bool enable = true);
 
         /**jsdoc
-         * Process the route without marking the controller output as having been read, so that other routes from the same 
+         * Processes the route without marking the controller output as having been read, so that other routes from the same 
          * controller output can also process.
          * @function RouteObject#peek
          * @param {boolean} [enable=true] - If <code>true</code> then the route is processed without marking the route's 
@@ -157,7 +157,7 @@ class RouteBuilderProxy : public QObject {
         Q_INVOKABLE QObject* peek(bool enable = true);
 
         /**jsdoc
-         * Process the route only if a condition is satisfied. The condition is evaluated before the route input is read, and 
+         * Processes the route only if a condition is satisfied. The condition is evaluated before the route input is read, and 
          * the input is read only if the condition is <code>true</code>. Thus, if the condition is not met then subsequent 
          * routes using the same input are processed.
          * @function RouteObject#when
@@ -170,6 +170,8 @@ class RouteBuilderProxy : public QObject {
          *         definition.</li>
          *     </ul>
          * <p>If an array of conditions is provided, their values are ANDed together.</p>
+         * <p><strong>Warning:</strong> The use of <code>!</code> is not currently supported in JavaScript <code>.when()</code> 
+         * calls.</p>
          * @returns {RouteObject} The <code>RouteObject</code> with the condition added.
          * @example <caption>Process the right trigger differently in HMD and desktop modes.</caption>
          * var MAPPING_NAME = "com.highfidelity.controllers.example.newMapping";
@@ -193,7 +195,7 @@ class RouteBuilderProxy : public QObject {
         Q_INVOKABLE QObject* when(const QScriptValue& expression);
 
         /**jsdoc
-         * Filter numeric route values to lie between two values; values outside this range are not passed on through the 
+         * Filters numeric route values to lie between two values; values outside this range are not passed on through the 
          * route.
          * @function RouteObject#clamp
          * @param {number} min - The minimum value to pass through.
@@ -214,7 +216,7 @@ class RouteBuilderProxy : public QObject {
         Q_INVOKABLE QObject* clamp(float min, float max);
 
         /**jsdoc
-         * Filter numeric route values such that they are rounded to <code>0</code> or <code>1</code> without output values 
+         * Filters numeric route values such that they are rounded to <code>0</code> or <code>1</code> without output values 
          * flickering when the input value hovers around <code>0.5</code>. For example, this enables you to use an analog input 
          * as if it were a toggle.
          * @function RouteObject#hysteresis
@@ -239,7 +241,7 @@ class RouteBuilderProxy : public QObject {
         Q_INVOKABLE QObject* hysteresis(float min, float max);
 
         /**jsdoc
-         * Filter numeric route values to send at a specified interval.
+         * Filters numeric route values to send at a specified interval.
          * @function RouteObject#pulse
          * @param {number} interval - The interval between sending values, in seconds.
          * @returns {RouteObject} The <code>RouteObject</code> with the filter applied.
@@ -258,7 +260,7 @@ class RouteBuilderProxy : public QObject {
         Q_INVOKABLE QObject* pulse(float interval);
 
         /**jsdoc
-         * Filter numeric and {@link Pose} route values to be scaled by a constant amount.
+         * Filters numeric and {@link Pose} route values to be scaled by a constant amount.
          * @function RouteObject#scale
          * @param {number} multiplier - The scale to multiply the value by.
          * @returns {RouteObject} The <code>RouteObject</code> with the filter applied.
@@ -280,7 +282,7 @@ class RouteBuilderProxy : public QObject {
         Q_INVOKABLE QObject* scale(float multiplier);
 
         /**jsdoc
-         * Filter numeric and {@link Pose} route values to have the opposite sign, e.g., <code>0.5</code> is changed to 
+         * Filters numeric and {@link Pose} route values to have the opposite sign, e.g., <code>0.5</code> is changed to 
          * <code>-0.5</code>.
          * @function RouteObject#invert
          * @returns {RouteObject} The <code>RouteObject</code> with the filter applied.
@@ -302,7 +304,7 @@ class RouteBuilderProxy : public QObject {
         Q_INVOKABLE QObject* invert();
 
         /**jsdoc
-         * Filter numeric route values such that they're sent only when the input value is outside a dead-zone. When the input 
+         * Filters numeric route values such that they're sent only when the input value is outside a dead-zone. When the input 
          * passes the dead-zone value, output is sent starting at <code>0.0</code> and catching up with the input value. As the 
          * input returns toward the dead-zone value, output values reduce to <code>0.0</code> at the dead-zone value.
          * @function RouteObject#deadZone
@@ -324,7 +326,7 @@ class RouteBuilderProxy : public QObject {
         Q_INVOKABLE QObject* deadZone(float min);
 
         /**jsdoc
-         * Filter numeric route values such that they are rounded to <code>-1</code>, <code>0</code>, or <code>1</code>.
+         * Filters numeric route values such that they are rounded to <code>-1</code>, <code>0</code>, or <code>1</code>.
          * For example, this enables you to use an analog input as if it were a toggle or, in the case of a bidirectional axis, 
          * a tri-state switch.
          * @function RouteObject#constrainToInteger
@@ -345,7 +347,7 @@ class RouteBuilderProxy : public QObject {
         Q_INVOKABLE QObject* constrainToInteger();
 
         /**jsdoc
-         * Filter numeric route values such that they are rounded to <code>0</code> or <code>1</code>. For example, this 
+         * Filters numeric route values such that they are rounded to <code>0</code> or <code>1</code>. For example, this 
          * enables you to use an analog input as if it were a toggle.
          * @function RouteObject#constrainToPositiveInteger
          * @returns {RouteObject} The <code>RouteObject</code> with the filter applied.
@@ -364,7 +366,7 @@ class RouteBuilderProxy : public QObject {
         Q_INVOKABLE QObject* constrainToPositiveInteger();
 
         /**jsdoc
-         * Filter {@link Pose} route values to have a pre-translation applied.
+         * Filters {@link Pose} route values to have a pre-translation applied.
          * @function RouteObject#translate
          * @param {Vec3} translate - The pre-translation to add to the pose.
          * @returns {RouteObject} The <code>RouteObject</code> with the pre-translation applied.
@@ -373,7 +375,7 @@ class RouteBuilderProxy : public QObject {
         Q_INVOKABLE QObject* translate(glm::vec3 translate);
 
         /**jsdoc
-         * Filter {@link Pose} route values to have a pre-transform applied.
+         * Filters {@link Pose} route values to have a pre-transform applied.
          * @function RouteObject#transform
          * @param {Mat4} transform - The pre-transform to apply.
          * @returns {RouteObject} The <code>RouteObject</code> with the pre-transform applied.
@@ -382,7 +384,7 @@ class RouteBuilderProxy : public QObject {
         Q_INVOKABLE QObject* transform(glm::mat4 transform);
 
         /**jsdoc
-         * Filter {@link Pose} route values to have a post-transform applied.
+         * Filters {@link Pose} route values to have a post-transform applied.
          * @function RouteObject#postTransform
          * @param {Mat4} transform - The post-transform to apply.
          * @returns {RouteObject} The <code>RouteObject</code> with the post-transform applied.
@@ -391,7 +393,7 @@ class RouteBuilderProxy : public QObject {
         Q_INVOKABLE QObject* postTransform(glm::mat4 transform);
 
         /**jsdoc
-         * Filter {@link Pose} route values to have a pre-rotation applied.
+         * Filters {@link Pose} route values to have a pre-rotation applied.
          * @function RouteObject#rotate
          * @param {Quat} rotation - The pre-rotation to add to the pose.
          * @returns {RouteObject} The <code>RouteObject</code> with the pre-rotation applied.
@@ -400,7 +402,7 @@ class RouteBuilderProxy : public QObject {
         Q_INVOKABLE QObject* rotate(glm::quat rotation);
 
         /**jsdoc
-         * Filter {@link Pose} route values to be smoothed by a low velocity filter. The filter's rotation and translation 
+         * Filters {@link Pose} route values to be smoothed by a low velocity filter. The filter's rotation and translation 
          * values are calculated as: <code>(1 - f) * currentValue + f * previousValue</code> where 
          * <code>f = currentVelocity / filterConstant</code>. At low velocities, the filter value is largely the previous 
          * value; at high velocities the value is wholly the current controller value.
@@ -415,7 +417,7 @@ class RouteBuilderProxy : public QObject {
         Q_INVOKABLE QObject* lowVelocity(float rotationConstant, float translationConstant);
 
         /**jsdoc
-         * Filter {@link Pose} route values to be smoothed by an exponential decay filter. The filter's rotation and 
+         * Filters {@link Pose} route values to be smoothed by an exponential decay filter. The filter's rotation and 
          * translation values are calculated as: <code>filterConstant * currentValue + (1 - filterConstant) * 
          * previousValue</code>. Values near 1 are less smooth with lower latency; values near 0 are more smooth with higher 
          * latency.
@@ -428,7 +430,7 @@ class RouteBuilderProxy : public QObject {
         Q_INVOKABLE QObject* exponentialSmoothing(float rotationConstant, float translationConstant);
 
         /**jsdoc
-         * Filter numeric route values such that a value of <code>0.0</code> is changed to <code>1.0</code>, and other values 
+         * Filters numeric route values such that a value of <code>0.0</code> is changed to <code>1.0</code>, and other values 
          * are changed to <code>0.0</code>.
          * @function RouteObject#logicalNot
          * @returns {RouteObject} The <code>RouteObject</code> with the filter applied.

libraries/input-plugins/src/input-plugins/KeyboardMouseDevice.cpp

@@ -219,9 +219,10 @@ controller::Input KeyboardMouseDevice::InputDevice::makeInput(KeyboardMouseDevic
 
 /**jsdoc
  * <p>The <code>Controller.Hardware.Keyboard</code> object has properties representing keyboard, mouse, and display touch 
- * events. The property values are integer IDs, uniquely identifying each output. <em>Read-only.</em> These can be mapped to 
+ * events. The property values are integer IDs, uniquely identifying each output. <em>Read-only.</em></p>
- * actions or functions or <code>Controller.Standard</code> items in a {@link RouteObject} mapping. For presses, each data 
+ * <p>These events can be mapped to actions or functions or <code>Controller.Standard</code> items in a {@link RouteObject}
- * value is either <code>1.0</code> for "true" or <code>0.0</code> for "false".</p>
+ * mapping. For presses, each data value is either <code>1.0</code> for "true" or <code>0.0</code> for "false".</p>
+ * 
  * <table>
  *   <thead>
  *     <tr><th>Property</th><th>Type</th><td>Data</th><th>Description</th></tr>
@@ -274,9 +275,13 @@ controller::Input KeyboardMouseDevice::InputDevice::makeInput(KeyboardMouseDevic
  *     <tr><td><code>MouseWheelLeft</code></td><td>number</td><td>number</td><td>The mouse wheel rotated left. The data value 
  *       is the number of units rotated (typically <code>1.0</code>).</td></tr>
  *     <tr><td><code>MouseWheelUp</code></td><td>number</td><td>number</td><td>The mouse wheel rotated up. The data value 
- *       is the number of units rotated (typically <code>1.0</code>).</td></tr>
+ *       is the number of units rotated (typically <code>1.0</code>).<br />
+ *       <strong>Warning:</strong> The mouse wheel in an ordinary mouse generates left/right wheel events instead of 
+ *       up/down.</td></tr>
  *     <tr><td><code>MouseWheelDown</code></td><td>number</td><td>number</td><td>The mouse wheel rotated down. The data value 
- *       is the number of units rotated (typically <code>1.0</code>).</td></tr>
+ *       is the number of units rotated (typically <code>1.0</code>).<br />
+ *       <strong>Warning:</strong> The mouse wheel in an ordinary mouse generates left/right wheel events instead of 
+ *       up/down.</td></tr>
   *     <tr><td><code>TouchpadRight</code></td><td>number</td><td>number</td><td>The average touch on a touch-enabled device 
  *       moved right. The data value is how far the average position of all touch points moved.</td></tr>
  *     <tr><td><code>TouchpadLeft</code></td><td>number</td><td>number</td><td>The average touch on a touch-enabled device 
@@ -288,7 +293,6 @@ controller::Input KeyboardMouseDevice::InputDevice::makeInput(KeyboardMouseDevic
   *   </tbody>
  * </table>
  * @typedef {object} Controller.Hardware-Keyboard
- * @todo <em>Currently, the mouse wheel in an ordinary mouse generates left/right wheel events instead of up/down.</em>
  */
 controller::Input::NamedVector KeyboardMouseDevice::InputDevice::getAvailableInputs() const {
     using namespace controller;

plugins/oculus/src/OculusControllerManager.cpp

@@ -409,9 +409,10 @@ void OculusControllerManager::TouchDevice::stopHapticPulse(bool leftHand) {
 }
 
 /**jsdoc
- * <p>The <code>Controller.Hardware.OculusTouch</code> object has properties representing Oculus Rift. The property values are 
+ * <p>The <code>Controller.Hardware.OculusTouch</code> object has properties representing the Oculus Rift. The property values 
- * integer IDs, uniquely identifying each output. <em>Read-only.</em> These can be mapped to actions or functions or 
+ * are integer IDs, uniquely identifying each output. <em>Read-only.</em></p>
- * <code>Controller.Standard</code> items in a {@link RouteObject} mapping.</p>
+ * <p>These outputs can be mapped to actions or functions or <code>Controller.Standard</code> items in a {@link RouteObject} 
+ * mapping.</p>
  * <table>
  *   <thead>
  *     <tr><th>Property</th><th>Type</th><th>Data</th><th>Description</th></tr>

plugins/openvr/src/ViveControllerManager.cpp

@@ -1299,14 +1299,20 @@ void ViveControllerManager::InputDevice::setConfigFromString(const QString& valu
 }
 
 /**jsdoc
- * <p>The <code>Controller.Hardware.Vive</code> object has properties representing Vive. The property values are integer IDs,
+ * <p>The <code>Controller.Hardware.Vive</code> object has properties representing the Vive. The property values are integer 
- * uniquely identifying each output. <em>Read-only.</em> These can be mapped to actions or functions or 
+ * IDs, uniquely identifying each output. <em>Read-only.</em></p>
- * <code>Controller.Standard</code> items in a {@link RouteObject} mapping.</p>
+ * <p>These outputs can be mapped to actions or functions or <code>Controller.Standard</code> items in a {@link RouteObject} 
+ * mapping.</p>
  * <table>
  *   <thead>
  *     <tr><th>Property</th><th>Type</th><th>Data</th><th>Description</th></tr>
  *   </thead>
  *   <tbody>
+ *     <tr><td colspan="4"><strong>Buttons</strong></td></tr>
+ *     <tr><td><code>LeftApplicationMenu</code></td><td>number</td><td>number</td><td>Left application menu button pressed.
+ *       </td></tr>
+ *     <tr><td><code>RightApplicationMenu</code></td><td>number</td><td>number</td><td>Right application menu button pressed.
+ *       </td></tr>
  *     <tr><td colspan="4"><strong>Touch Pad (Sticks)</strong></td></tr>
  *     <tr><td><code>LX</code></td><td>number</td><td>number</td><td>Left touch pad x-axis scale.</td></tr>
  *     <tr><td><code>LY</code></td><td>number</td><td>number</td><td>Left touch pad y-axis scale.</td></tr>