Merge pull request #15676 from ctrlaltdavid/DOC-33

DOC-33: MyAvatar API JSDoc catch-up

assignment-client/src/avatars/ScriptableAvatar.h

@@ -74,7 +74,8 @@
  *     avatar. <em>Read-only.</em>
  * @property {number} sensorToWorldScale - The scale that transforms dimensions in the user's real world to the avatar's
  *     size in the virtual world. <em>Read-only.</em>
- * @property {boolean} hasPriority - is the avatar in a Hero zone? <em>Read-only.</em>
+ * @property {boolean} hasPriority - <code>true</code> if the avatar is in a "hero" zone, <code>false</code> if it isn't.
+ *     <em>Read-only.</em>
  *
  * @example <caption>Create a scriptable avatar.</caption>
  * (function () {
@@ -138,6 +139,9 @@ public:
     /// Returns the index of the joint with the specified name, or -1 if not found/unknown.
     Q_INVOKABLE virtual int getJointIndex(const QString& name) const override;
 
+    /**jsdoc
+     * @comment Uses the base class's JSDoc.
+     */
     Q_INVOKABLE virtual void setSkeletonModelURL(const QUrl& skeletonModelURL) override;
 
     /**jsdoc

interface/src/avatar/MyAvatar.h

@@ -39,6 +39,23 @@ class ModelItemID;
 class MyHead;
 class DetailedMotionState;
 
+/**jsdoc
+ * <p>Locomotion control types.</p>
+ * <table>
+ *   <thead>
+ *     <tr><th>Value</th><th>Name</th><th>Description</th></tr>
+ *   </thead>
+ *   <tbody>
+ *     <tr><td><code>0</code></td><td>Default</td><td>Your walking speed is constant; it doesn't change depending on how far 
+ *       forward you push your controller's joystick. Fully pushing your joystick forward makes your avatar run.</td></tr>
+ *     <tr><td><code>1</code></td><td>Analog</td><td>Your walking speed changes in steps based on how far forward you push your 
+ *       controller's joystick. Fully pushing your joystick forward makes your avatar run.</td></tr>
+ *     <tr><td><code>2</code></td><td>AnalogPlus</td><td>Your walking speed changes proportionally to how far forward you push 
+ *       your controller's joystick. Fully pushing your joystick forward makes your avatar run.</td></tr>
+ *   </tbody>
+ * </table>
+ * @typedef {number} MyAvatar.LocomotionControlsMode
+ */
 enum LocomotionControlsMode {
     CONTROLS_DEFAULT = 0,
     CONTROLS_ANALOG,
@@ -128,6 +145,8 @@ class MyAvatar : public Avatar {
      *     avatar. <em>Read-only.</em>
      * @property {number} sensorToWorldScale - The scale that transforms dimensions in the user's real world to the avatar's
      *     size in the virtual world. <em>Read-only.</em>
+     * @property {boolean} hasPriority - <code>true</code> if the avatar is in a "hero" zone, <code>false</code> if it isn't.
+     *     <em>Read-only.</em>
      *
      * @comment IMPORTANT: This group of properties is copied from Avatar.h; they should NOT be edited here.
      * @property {Vec3} skeletonOffset - Can be used to apply a translation offset between the avatar's position and the
@@ -239,9 +258,16 @@ class MyAvatar : public Avatar {
      *     where MyAvatar.sessionUUID is not available (e.g., if not connected to a domain). Note: Likely to be deprecated. 
      *     <em>Read-only.</em>
      *
-     * @property {number} walkSpeed - The walk speed of your avatar.
+     * @property {number} walkSpeed - The walk speed of your avatar for the current control scheme (see 
-     * @property {number} walkBackwardSpeed - The walk backward speed of your avatar.
+     *     {@link MyAvatar.getControlScheme|getControlScheme}).
-     * @property {number} sprintSpeed - The sprint speed of your avatar.
+     * @property {number} walkBackwardSpeed - The walk backward speed of your avatar for the current control scheme (see 
+     *     {@link MyAvatar.getControlScheme|getControlScheme}).
+     * @property {number} sprintSpeed - The sprint (run) speed of your avatar for the current control scheme (see 
+     *     {@link MyAvatar.getControlScheme|getControlScheme}).
+     * @property {number} analogPlusWalkSpeed - The walk speed of your avatar for the "AnalogPlus" control scheme.
+     *     <p><strong>Warning:</strong> Setting this value also sets the value of <code>analogPlusSprintSpeed</code> to twice 
+     *     the value.</p>
+     * @property {number} analogPlusSprintSpeed - The sprint speed of your avatar for the "AnalogPlus" control scheme.
      * @property {MyAvatar.SitStandModelType} userRecenterModel - Controls avatar leaning and recentering behavior.
      * @property {number} isInSittingState - <code>true</code> if your avatar is sitting (avatar leaning is disabled, 
      *     recenntering is enabled), <code>false</code> if it is standing (avatar leaning is enabled, and avatar recenters if it 
@@ -281,6 +307,7 @@ class MyAvatar : public Avatar {
      * @borrows Avatar.updateAvatarEntity as updateAvatarEntity
      * @borrows Avatar.clearAvatarEntity as clearAvatarEntity
      * @borrows Avatar.setForceFaceTrackerConnected as setForceFaceTrackerConnected
+     * @borrows Avatar.setSkeletonModelURL as setSkeletonModelURL
      * @borrows Avatar.getAttachmentData as getAttachmentData
      * @borrows Avatar.setAttachmentData as setAttachmentData
      * @borrows Avatar.attach as attach
@@ -308,7 +335,6 @@ class MyAvatar : public Avatar {
      * @comment Avatar.setAbsoluteJointTranslationInObjectFrame as setAbsoluteJointTranslationInObjectFrame - Don't borrow because implementation is different.
      * @borrows Avatar.getTargetScale as getTargetScale
      * @borrows Avatar.resetLastSent as resetLastSent
-     * @borrows Avatar.hasPriority as hasPriority
      */
     // FIXME: `glm::vec3 position` is not accessible from QML, so this exposes position in a QML-native type
     Q_PROPERTY(QVector3D qmlPosition READ getQmlPosition)
@@ -583,14 +609,13 @@ public:
      * the avatar will move in unpredictable ways. For more information about avatar joint orientation standards, see 
      * <a href="https://docs.highfidelity.com/create/avatars/avatar-standards">Avatar Standards</a>.</p>
      * @function MyAvatar.overrideAnimation
-     * @param url {string} The URL to the animation file. Animation files need to be FBX format, but only need to contain the 
+     * @param {string} url - The URL to the animation file. Animation files need to be FBX format, but only need to contain the 
      * avatar skeleton and animation data.
-     * @param fps {number} The frames per second (FPS) rate for the animation playback. 30 FPS is normal speed.
+     * @param {number} fps - The frames per second (FPS) rate for the animation playback. 30 FPS is normal speed.
-     * @param loop {boolean} Set to true if the animation should loop.
+     * @param {boolean} loop - <code>true</code> if the animation should loop, <code>false</code> if it shouldn't.
-     * @param firstFrame {number} The frame the animation should start at.
+     * @param {number} firstFrame - The frame to start the animation at.
-     * @param lastFrame {number} The frame the animation should end at.
+     * @param {number} lastFrame - The frame to end the animation at.
      * @example <caption> Play a clapping animation on your avatar for three seconds. </caption>
-     * // Clap your hands for 3 seconds then restore animation back to the avatar.
      * var ANIM_URL = "https://s3.amazonaws.com/hifi-public/animations/ClapAnimations/ClapHands_Standing.fbx";
      * MyAvatar.overrideAnimation(ANIM_URL, 30, true, 0, 53);
      * Script.setTimeout(function () {
@@ -601,18 +626,18 @@ public:
     Q_INVOKABLE void overrideAnimation(const QString& url, float fps, bool loop, float firstFrame, float lastFrame);
 
     /**jsdoc
-     * <code>overrideHandAnimation()</code> Gets the overrides the default hand poses that are triggered with controller buttons.
+     * Overrides the default hand poses that are triggered with controller buttons.
-     * use {@link MyAvatar.restoreHandAnimation}.</p> to restore the default poses.
+     * Use {@link MyAvatar.restoreHandAnimation} to restore the default poses.
      * @function MyAvatar.overrideHandAnimation
-     * @param isLeft {boolean} Set true if using the left hand
+     * @param isLeft {boolean} <code>true</code> to override the left hand, <code>false</code> to override the right hand.
-     * @param url {string} The URL to the animation file. Animation files need to be FBX format, but only need to contain the
+     * @param {string} url - The URL of the animation file. Animation files need to be FBX format, but only need to contain the
      * avatar skeleton and animation data.
-     * @param fps {number} The frames per second (FPS) rate for the animation playback. 30 FPS is normal speed.
+     * @param {number} fps - The frames per second (FPS) rate for the animation playback. 30 FPS is normal speed.
-     * @param loop {boolean} Set to true if the animation should loop.
+     * @param {boolean} loop - <code>true</code> if the animation should loop, <code>false</code> if it shouldn't.
-     * @param firstFrame {number} The frame the animation should start at.
+     * @param {number} firstFrame - The frame to start the animation at.
-     * @param lastFrame {number} The frame the animation should end at
+     * @param {number} lastFrame - The frame to end the animation at.
-     * @example <caption> Override left hand animation for three seconds. </caption>
+     * @example <caption> Override left hand animation for three seconds.</caption>
-     * // Override the left hand pose then restore the default pose.
+     * var ANIM_URL = "https://s3.amazonaws.com/hifi-public/animations/ClapAnimations/ClapHands_Standing.fbx";
      * MyAvatar.overrideHandAnimation(isLeft, ANIM_URL, 30, true, 0, 53);
      * Script.setTimeout(function () {
      *     MyAvatar.restoreHandAnimation();
@@ -629,7 +654,6 @@ public:
      * animation, this function has no effect.</p>
      * @function MyAvatar.restoreAnimation
      * @example <caption> Play a clapping animation on your avatar for three seconds. </caption>
-     * // Clap your hands for 3 seconds then restore animation back to the avatar.
      * var ANIM_URL = "https://s3.amazonaws.com/hifi-public/animations/ClapAnimations/ClapHands_Standing.fbx";
      * MyAvatar.overrideAnimation(ANIM_URL, 30, true, 0, 53);
      * Script.setTimeout(function () {
@@ -639,16 +663,15 @@ public:
     Q_INVOKABLE void restoreAnimation();
 
     /**jsdoc
-     * Restores the default hand animation state machine that is driven by the state machine in the avatar-animation json.
+     * Restores the default hand animation state machine that is driven by the state machine in the avatar-animation JSON.
      * <p>The avatar animation system includes a set of default animations along with rules for how those animations are blended
      * together with procedural data (such as look at vectors, hand sensors etc.). Playing your own custom animations will
-     * override the  default animations. <code>restoreHandAnimation()</code> is used to restore the default hand poses
+     * override the  default animations. <code>restoreHandAnimation()</code> is used to restore the default hand poses.
-     * If you aren't currently playing an override hand
+     * If you aren't currently playing an override hand animation, this function has no effect.</p>
-     * animation, this function has no effect.</p>
      * @function MyAvatar.restoreHandAnimation
      * @param isLeft {boolean} Set to true if using the left hand
      * @example <caption> Override left hand animation for three seconds. </caption>
-     * // Override the left hand pose then restore the default pose.
+     * var ANIM_URL = "https://s3.amazonaws.com/hifi-public/animations/ClapAnimations/ClapHands_Standing.fbx";
      * MyAvatar.overrideHandAnimation(isLeft, ANIM_URL, 30, true, 0, 53);
      * Script.setTimeout(function () {
      *     MyAvatar.restoreHandAnimation();
@@ -689,12 +712,13 @@ public:
      * the avatar will move in unpredictable ways. For more information about avatar joint orientation standards, see 
      * <a href="https://docs.highfidelity.com/create/avatars/avatar-standards">Avatar Standards</a>.
      * @function MyAvatar.overrideRoleAnimation
-     * @param role {string} The animation role to override
+     * @param {string} role - The animation role to override
-     * @param url {string} The URL to the animation file. Animation files need to be in FBX format, but only need to contain the avatar skeleton and animation data.
+     * @param {string} url - The URL to the animation file. Animation files need to be in FBX format, but only need to contain 
-     * @param fps {number} The frames per second (FPS) rate for the animation playback. 30 FPS is normal speed.
+     *     the avatar skeleton and animation data.
-     * @param loop {boolean} Set to true if the animation should loop
+     * @param {number} fps - The frames per second (FPS) rate for the animation playback. 30 FPS is normal speed.
-     * @param firstFrame {number} The frame the animation should start at
+     * @param {boolean} loop - <code>true</code> if the animation should loop, <code>false</code> if it shouldn't.
-     * @param lastFrame {number} The frame the animation should end at
+     * @param {number} firstFrame - The frame the animation should start at.
+     * @param {number} lastFrame - The frame the animation should end at.
      * @example <caption>The default avatar-animation.json defines an "idleStand" animation role. This role specifies that when the avatar is not moving,
      * an animation clip of the avatar idling with hands hanging at its side will be used. It also specifies that when the avatar moves, the animation
      * will smoothly blend to the walking animation used by the "walkFwd" animation role.
@@ -782,33 +806,42 @@ public:
      *     mode.
      */
     Q_INVOKABLE bool getSnapTurn() const { return _useSnapTurn; }
+
     /**jsdoc
-     * Sets whether your should do snap turns or smooth turns in HMD mode.
+     * Sets whether you do snap turns or smooth turns in HMD mode.
      * @function MyAvatar.setSnapTurn
      * @param {boolean} on - <code>true</code> to do snap turns in HMD mode; <code>false</code> to do smooth turns in HMD mode.
      */
     Q_INVOKABLE void setSnapTurn(bool on) { _useSnapTurn = on; }
 
-    /**
+    /**jsdoc
+     * Gets the control scheme that is in use.
      * @function MyAvatar.getControlScheme
-     * @returns {number}
+     * @returns {MyAvatar.LocomotionControlsMode} The control scheme that is in use.
-    */
+     */
     Q_INVOKABLE int getControlScheme() const { return _controlSchemeIndex; }
 
-    /**
+    /**jsdoc
+     * Sets the control scheme to use.
      * @function MyAvatar.setControlScheme
-     * @param {number} index
+     * @param {MyAvatar.LocomotionControlsMode} controlScheme - The control scheme to use.
-    */
+     */
     Q_INVOKABLE void setControlScheme(int index) { _controlSchemeIndex = (index >= 0 && index <= 2) ? index : 0; }
     
     /**jsdoc
+     * Gets whether your avatar hovers when its feet are not on the ground.
      * @function MyAvatar.hoverWhenUnsupported
-     * @returns {boolean} 
+     * @returns {boolean} <code>true</code> if your avatar hovers when its feet are not on the ground, <code>false</code> if it 
+     *     falls.
      */
+    // FIXME: Should be named, getHoverWhenUnsupported().
     Q_INVOKABLE bool hoverWhenUnsupported() const { return _hoverWhenUnsupported; }
+
     /**jsdoc
+     * Sets whether your avatar hovers when its feet are not on the ground.
      * @function MyAvatar.setHoverWhenUnsupported
-     * @param {boolean} on
+     * @param {boolean} hover - <code>true</code> if your avatar hovers when its feet are not on the ground, <code>false</code> 
+     *     if it falls.
      */
     Q_INVOKABLE void setHoverWhenUnsupported(bool on) { _hoverWhenUnsupported = on; }
 
@@ -826,26 +859,31 @@ public:
      * @returns {string} <code>"left"</code> for the left hand, <code>"right"</code> for the right hand.
      */
     Q_INVOKABLE QString getDominantHand() const;
+
     /**jsdoc
-    * @function MyAVatar.setStrafeEnabled
+     * Sets whether strafing is enabled.
-    * @param {bool} enabled
+     * @function MyAvatar.setStrafeEnabled
-    */
+     * @param {boolean} enabled - <code>true</code> if strafing is enabled, <code>false</code> if it isn't.
+     */
     Q_INVOKABLE void setStrafeEnabled(bool enabled);
+
     /**jsdoc
-    * @function MyAvatar.getStrafeEnabled
+     * Gets whether strafing is enabled.
-    * @returns {bool}
+     * @function MyAvatar.getStrafeEnabled
-    */
+     * @returns {boolean} <code>true</code> if strafing is enabled, <code>false</code> if it isn't.
+     */
     Q_INVOKABLE bool getStrafeEnabled() const;
+
     /**jsdoc
+     * Sets the HMD alignment relative to your avatar.
      * @function MyAvatar.setHmdAvatarAlignmentType
      * @param {string} type - <code>"head"</code> to align your head and your avatar's head, <code>"eyes"</code> to align your 
      *     eyes and your avatar's eyes.
-     *     
      */
     Q_INVOKABLE void setHmdAvatarAlignmentType(const QString& type);
 
     /**jsdoc
-     * Gets the HMD alignment for your avatar.
+     * Gets the HMD alignment relative to your avatar.
      * @function MyAvatar.getHmdAvatarAlignmentType
      * @returns {string} <code>"head"</code> if aligning your head and your avatar's head, <code>"eyes"</code> if aligning your 
      *     eyes and your avatar's eyes.
@@ -1495,18 +1533,8 @@ public:
     */
     Q_INVOKABLE float getDriveGear5();
 
-    /**jsdoc
-     * Choose the control scheme.
-     * @function MyAvatar.setControlSchemeIndex
-     * @param {number} Choose the control scheme to be used.
-     */
     void setControlSchemeIndex(int index);
 
-    /**jsdoc
-     * Check what control scheme is in use.
-     * @function MyAvatar.getControlSchemeIndex
-     * @returns {number} Returns the index associated with a given control scheme.
-     */
     int getControlSchemeIndex();
 
     /**jsdoc
@@ -1584,8 +1612,8 @@ public:
     Q_INVOKABLE bool getCharacterControllerEnabled(); // deprecated
 
     /**jsdoc
-     * @comment Different behavior to the Avatar version of this method.
      * Gets the rotation of a joint relative to the avatar.
+     * @comment Different behavior to the Avatar version of this method.
      * @function MyAvatar.getAbsoluteJointRotationInObjectFrame
      * @param {number} index - The index of the joint.
      * @returns {Quat} The rotation of the joint relative to the avatar.
@@ -1597,8 +1625,8 @@ public:
     virtual glm::quat getAbsoluteJointRotationInObjectFrame(int index) const override;
 
     /**jsdoc
-     * @comment Different behavior to the Avatar version of this method.
      * Gets the translation of a joint relative to the avatar.
+     * @comment Different behavior to the Avatar version of this method.
      * @function MyAvatar.getAbsoluteJointTranslationInObjectFrame
      * @param {number} index - The index of the joint.
      * @returns {Vec3} The translation of the joint relative to the avatar.
@@ -2441,6 +2469,9 @@ private:
     void updateEyeContactTarget(float deltaTime);
 
     // These are made private for MyAvatar so that you will use the "use" methods instead
+    /**jsdoc
+     * @comment Borrows the base class's JSDoc.
+     */
     Q_INVOKABLE virtual void setSkeletonModelURL(const QUrl& skeletonModelURL) override;
 
     virtual void updatePalms() override {}

libraries/avatars/src/AvatarData.h

@@ -1211,6 +1211,12 @@ public:
     const QString& getDisplayName() const { return _displayName; }
     const QString& getSessionDisplayName() const { return _sessionDisplayName; }
     bool getLookAtSnappingEnabled() const { return _lookAtSnappingEnabled; }
+
+    /**jsdoc
+     * Sets the avatar's skeleton model.
+     * @function Avatar.setSkeletonModelURL
+     * @param {string} url - The avatar's FST file.
+     */
     Q_INVOKABLE virtual void setSkeletonModelURL(const QUrl& skeletonModelURL);
 
     virtual void setDisplayName(const QString& displayName);