Merge pull request #15823 from ctrlaltdavid/DOC-79

DOC-79: Entities JSDoc Update

interface/src/avatar/AvatarActionFarGrab.h

@@ -19,13 +19,15 @@
  * The <code>"far-grab"</code> {@link Entities.ActionType|ActionType} moves and rotates an entity to a target position and 
  * orientation, optionally relative to another entity. Collisions between the entity and the user's avatar are disabled during 
  * the far-grab.
- * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}.
+ * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}:
  *
  * @typedef {object} Entities.ActionArguments-FarGrab
+ * @property {Uuid} otherID=null - If an entity ID, the <code>targetPosition</code> and <code>targetRotation</code> are
+ *     relative to the entity's position and rotation.
+ * @property {Uuid} otherJointIndex=null - If a joint index in the <code>otherID</code> entity, the <code>targetPosition</code>
+ *     and <code>targetRotation</code> are relative to the entity joint's position and rotation.
  * @property {Vec3} targetPosition=0,0,0 - The target position.
  * @property {Quat} targetRotation=0,0,0,1 - The target rotation.
- * @property {Uuid} otherID=null - If an entity ID, the <code>targetPosition</code> and <code>targetRotation</code> are 
- *     relative to this entity's position and rotation.
  * @property {number} linearTimeScale=3.4e+38 - Controls how long it takes for the entity's position to catch up with the
  *     target position. The value is the time for the action to catch up to 1/e = 0.368 of the target value, where the action 
  *     is applied using an exponential decay.
@@ -33,6 +35,7 @@
  *     target orientation. The value is the time for the action to catch up to 1/e = 0.368 of the target value, where the 
  *     action is applied using an exponential decay.
  */
+// The properties are per ObjectActionTractor.
 class AvatarActionFarGrab : public ObjectActionTractor {
 public:
     AvatarActionFarGrab(const QUuid& id, EntityItemPointer ownerEntity);

interface/src/avatar/AvatarActionHold.cpp

@@ -447,16 +447,16 @@ bool AvatarActionHold::updateArguments(QVariantMap arguments) {
 /**jsdoc
  * The <code>"hold"</code> {@link Entities.ActionType|ActionType} positions and rotates an entity relative to an avatar's hand. 
  * Collisions between the entity and the user's avatar are disabled during the hold.
- * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}.
+ * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}:
  *
  * @typedef {object} Entities.ActionArguments-Hold
  * @property {Uuid} holderID=MyAvatar.sessionUUID - The ID of the avatar holding the entity.
+ * @property {string} hand=right - The hand holding the entity: <code>"left"</code> or <code>"right"</code>.
  * @property {Vec3} relativePosition=0,0,0 - The target position relative to the avatar's hand.
  * @property {Vec3} relativeRotation=0,0,0,1 - The target rotation relative to the avatar's hand.
  * @property {number} timeScale=3.4e+38 - Controls how long it takes for the entity's position and rotation to catch up with 
  *     the target. The value is the time for the action to catch up to 1/e = 0.368 of the target value, where the action is 
  *     applied using an exponential decay.
- * @property {string} hand=right - The hand holding the entity: <code>"left"</code> or <code>"right"</code>.
  * @property {boolean} kinematic=false - If <code>true</code>, the entity is made kinematic during the action; the entity won't 
  *    lag behind the hand but constraint actions such as <code>"hinge"</code> won't act properly.
  * @property {boolean} kinematicSetVelocity=false - If <code>true</code> and <code>kinematic</code> is <code>true</code>, the 

interface/src/scripting/TestScriptingInterface.h

@@ -165,14 +165,14 @@ public slots:
 
     /**jsdoc
      * Set number of cycles texture size is required to be stable
-     * @function Entities.setMinimumGPUTextureMemStabilityCount
+     * @function Test.setMinimumGPUTextureMemStabilityCount
     * @param {number} count - Number of cycles to wait
      */
     Q_INVOKABLE void setMinimumGPUTextureMemStabilityCount(int count);
 
     /**jsdoc
      * Check whether all textures have been loaded.
-     * @function Entities.isTextureLoadingComplete
+     * @function Test.isTextureLoadingComplete
      * @returns {boolean} <code>true</code> texture memory usage is not increasing
      */
     Q_INVOKABLE bool isTextureLoadingComplete();

libraries/entities/src/AmbientLightPropertyGroup.h

@@ -28,7 +28,7 @@ class EntityTreeElementExtraEncodeData;
 class ReadBitstreamToTreeParams;
 
 /**jsdoc
- * Ambient light is defined by the following properties.
+ * Ambient light is defined by the following properties:
  * @typedef {object} Entities.AmbientLight
  * @property {number} ambientIntensity=0.5 - The intensity of the light.
  * @property {string} ambientURL="" - A cube map image that defines the color of the light coming from each direction. If 

libraries/entities/src/AnimationPropertyGroup.cpp

@@ -48,16 +48,18 @@ bool operator!=(const AnimationPropertyGroup& a, const AnimationPropertyGroup& b
 
 
 /**jsdoc
- * The AnimationProperties are used to configure an animation.
+ * An animation is configured by the following properties:
  * @typedef {object} Entities.AnimationProperties
  * @property {string} url="" - The URL of the FBX file that has the animation.
+ * @property {boolean} allowTranslation=true - <code>true</code> to enable translations contained in the animation to be 
+ *     played, <code>false</code> to disable translations.
  * @property {number} fps=30 - The speed in frames/s that the animation is played at.
  * @property {number} firstFrame=0 - The first frame to play in the animation.
  * @property {number} lastFrame=100000 - The last frame to play in the animation.
  * @property {number} currentFrame=0 - The current frame being played in the animation.
  * @property {boolean} running=false - If <code>true</code> then the animation should play.
- * @property {boolean} loop=true - If <code>true</code> then the animation should be continuously repeated in a loop.
+ * @property {boolean} loop=true - If <code>true</code> then the animation is continuously repeated in a loop.
- * @property {boolean} hold=false - If <code>true</code> then the rotations and translations of the last frame played should be
+ * @property {boolean} hold=false - If <code>true</code> then the rotations and translations of the last frame played are 
  *     maintained when the animation stops playing.
  */
 void AnimationPropertyGroup::copyToScriptValue(const EntityPropertyFlags& desiredProperties, QScriptValue& properties, QScriptEngine* engine, bool skipDefaults, EntityItemProperties& defaultEntityProperties) const {

libraries/entities/src/BloomPropertyGroup.h

@@ -31,9 +31,8 @@ static const float INITIAL_BLOOM_THRESHOLD { 0.7f };
 static const float INITIAL_BLOOM_SIZE { 0.9f };
 
 /**jsdoc
- * Bloom is defined by the following properties.
+ * Bloom is defined by the following properties:
  * @typedef {object} Entities.Bloom
- *
  * @property {number} bloomIntensity=0.25 - The intensity of the bloom effect.
  * @property {number} bloomThreshold=0.7 - The threshold for the bloom effect.
  * @property {number} bloomSize=0.9 - The size of the bloom effect.

libraries/entities/src/EntityDynamicInterface.cpp

@@ -94,47 +94,48 @@ variables.  These argument variables are used by the code which is run when bull
 #include "EntityItem.h"
 
 /**jsdoc
-* <p>An entity action may be one of the following types:</p>
+ * <p>An entity action may be one of the following types:</p>
-* <table>
+ * <table>
-*   <thead>
+ *   <thead>
-*     <tr><th>Value</th><th>Type</th><th>Description</th><th>Arguments</th></tr>
+ *     <tr><th>Value</th><th>Type</th><th>Description</th><th>Arguments</th></tr>
-*   </thead>
+ *   </thead>
-*   <tbody>
+ *   <tbody>
-*     <tr><td><code>"far-grab"</code></td><td>Avatar action</td>
+ *     <tr><td><code>"far-grab"</code></td><td>Avatar action</td>
-*       <td>Moves and rotates an entity to a target position and orientation, optionally relative to another entity. Collisions 
+ *       <td>Moves and rotates an entity to a target position and orientation, optionally relative to another entity. Collisions 
-*       between the entity and the user's avatar are disabled during the far-grab.</td>
+ *       between the entity and the user's avatar are disabled during the far-grab.</td>
-*       <td>{@link Entities.ActionArguments-FarGrab}</td></tr>
+ *       <td>{@link Entities.ActionArguments-FarGrab}</td></tr>
-*     <tr><td><code>"hold"</code></td><td>Avatar action</td>
+ *     <tr><td><code>"hold"</code></td><td>Avatar action</td>
-*       <td>Positions and rotates an entity relative to an avatar's hand. Collisions between the entity and the user's avatar 
+ *       <td>Positions and rotates an entity relative to an avatar's hand. Collisions between the entity and the user's avatar 
-*       are disabled during the hold.</td>
+ *       are disabled during the hold.</td>
-*       <td>{@link Entities.ActionArguments-Hold}</td></tr>
+ *       <td>{@link Entities.ActionArguments-Hold}</td></tr>
-*     <tr><td><code>"offset"</code></td><td>Object action</td>
+ *     <tr><td><code>"offset"</code></td><td>Object action</td>
-*       <td>Moves an entity so that it is a set distance away from a target point.</td>
+ *       <td>Moves an entity so that it is a set distance away from a target point.</td>
-*       <td>{@link Entities.ActionArguments-Offset}</td></tr>
+ *       <td>{@link Entities.ActionArguments-Offset}</td></tr>
-*     <tr><td><code>"tractor"</code></td><td>Object action</td>
+ *     <tr><td><code>"tractor"</code></td><td>Object action</td>
-*       <td>Moves and rotates an entity to a target position and orientation, optionally relative to another entity.</td>
+ *       <td>Moves and rotates an entity to a target position and orientation, optionally relative to another entity.</td>
-*       <td>{@link Entities.ActionArguments-Tractor}</td></tr>
+ *       <td>{@link Entities.ActionArguments-Tractor}</td></tr>
-*     <tr><td><code>"travel-oriented"</code></td><td>Object action</td>
+ *     <tr><td><code>"travel-oriented"</code></td><td>Object action</td>
-*       <td>Orients an entity to align with its direction of travel.</td>
+ *       <td>Orients an entity to align with its direction of travel.</td>
-*       <td>{@link Entities.ActionArguments-TravelOriented}</td></tr>
+ *       <td>{@link Entities.ActionArguments-TravelOriented}</td></tr>
-*     <tr><td><code>"hinge"</code></td><td>Object constraint</td>
+ *     <tr><td><code>"hinge"</code></td><td>Object constraint</td>
-*       <td>Lets an entity pivot about an axis or connects two entities with a hinge joint.</td>
+ *       <td>Lets an entity pivot about an axis or connects two entities with a hinge joint.</td>
-*       <td>{@link Entities.ActionArguments-Hinge}</td></tr>
+ *       <td>{@link Entities.ActionArguments-Hinge}</td></tr>
-*     <tr><td><code>"slider"</code></td><td>Object constraint</td>
+ *     <tr><td><code>"slider"</code></td><td>Object constraint</td>
-*       <td>Lets an entity slide and rotate along an axis, or connects two entities that slide and rotate along a shared 
+ *       <td>Lets an entity slide and rotate along an axis, or connects two entities that slide and rotate along a shared 
-*       axis.</td>
+ *       axis.</td>
-*       <td>{@link Entities.ActionArguments-Slider|ActionArguments-Slider}</td></tr>
+ *       <td>{@link Entities.ActionArguments-Slider|ActionArguments-Slider}</td></tr>
-*     <tr><td><code>"cone-twist"</code></td><td>Object constraint</td>
+ *     <tr><td><code>"cone-twist"</code></td><td>Object constraint</td>
-*       <td>Connects two entities with a joint that can move through a cone and can twist.</td>
+ *       <td>Connects two entities with a joint that can move through a cone and can twist.</td>
-*       <td>{@link Entities.ActionArguments-ConeTwist}</td></tr>
+ *       <td>{@link Entities.ActionArguments-ConeTwist}</td></tr>
-*     <tr><td><code>"ball-socket"</code></td><td>Object constraint</td>
+ *     <tr><td><code>"ball-socket"</code></td><td>Object constraint</td>
-*       <td>Connects two entities with a ball and socket joint.</td>
+ *       <td>Connects two entities with a ball and socket joint.</td>
-*       <td>{@link Entities.ActionArguments-BallSocket}</td></tr>
+ *       <td>{@link Entities.ActionArguments-BallSocket}</td></tr>
-*     <tr><td><code>"spring"</code></td><td colspan="3">Synonym for <code>"tractor"</code>. <em>Legacy value.</em></td></tr>
+ *     <tr><td><code>"spring"</code></td><td colspan="3">Synonym for <code>"tractor"</code>. 
-*   </tbody>
+ *       <span class="important">Deprecated.</span></td></tr>
-* </table>
+ *   </tbody>
-* @typedef {string} Entities.ActionType
+ * </table>
-*/
+ * @typedef {string} Entities.ActionType
+ */
 // Note: The "none" action type is not listed because it's an internal "uninitialized" value and not useful for scripts.
 EntityDynamicType EntityDynamicInterface::dynamicTypeFromString(QString dynamicTypeString) {
     QString normalizedDynamicTypeString = dynamicTypeString.toLower().remove('-').remove('_');

libraries/entities/src/EntityTypes.h

@@ -42,7 +42,10 @@ public:
      *     <tr><th>Value</th><th>Description</th><th>Properties</th></tr>
      *   </thead>
      *   <tbody>
-     *     <tr><td><code>"Box"</code></td><td>A rectangular prism. This is a synonym of <code>"Shape"</code> for the case 
+     *     <tr><td><code>"Shape"</code></td><td>A basic entity such as a cube.
+     *       See also, the <code>"Box"</code> and <code>"Sphere"</code> entity types.</td>
+     *       <td>{@link Entities.EntityProperties-Shape|EntityProperties-Shape}</td></tr>
+     *     <tr><td><code>"Box"</code></td><td>A rectangular prism. This is a synonym of <code>"Shape"</code> for the case
      *       where the entity's <code>shape</code> property value is <code>"Cube"</code>.<br />
      *       If an entity is created with its <code>type</code> 
      *       set to <code>"Box"</code> it will always be created with a <code>shape</code> property value of 
@@ -56,16 +59,13 @@ public:
      *       <code>"Sphere"</code>. If an entity of type <code>Box</code> or <code>Shape</code> has its <code>shape</code> set
      *       to <code>"Sphere"</code> then its <code>type</code> will be reported as <code>"Sphere"</code>.
      *       <td>{@link Entities.EntityProperties-Sphere|EntityProperties-Sphere}</td></tr>
-     *     <tr><td><code>"Shape"</code></td><td>A basic entity such as a cube.
+     *     <tr><td><code>"Model"</code></td><td>A mesh model from a glTf, FBX, or OBJ file.</td>
-     *       See also, the <code>"Box"</code> and <code>"Sphere"</code> entity types.</td>
-     *       <td>{@link Entities.EntityProperties-Shape|EntityProperties-Shape}</td></tr>
-     *     <tr><td><code>"Model"</code></td><td>A mesh model from an FBX or OBJ file.</td>
      *       <td>{@link Entities.EntityProperties-Model|EntityProperties-Model}</td></tr>
      *     <tr><td><code>"Text"</code></td><td>A pane of text oriented in space.</td>
      *       <td>{@link Entities.EntityProperties-Text|EntityProperties-Text}</td></tr>
      *     <tr><td><code>"Image"</code></td><td>An image oriented in space.</td>
      *       <td>{@link Entities.EntityProperties-Image|EntityProperties-Image}</td></tr>
-     *     <tr><td><code>"Web"</code></td><td>A browsable Web page.</td>
+     *     <tr><td><code>"Web"</code></td><td>A browsable web page.</td>
      *       <td>{@link Entities.EntityProperties-Web|EntityProperties-Web}</td></tr>
      *     <tr><td><code>"ParticleEffect"</code></td><td>A particle system that can be used to simulate things such as fire, 
      *       smoke, snow, magic spells, etc.</td>
@@ -78,7 +78,7 @@ public:
      *       <td>{@link Entities.EntityProperties-PolyVox|EntityProperties-PolyVox}</td></tr>
      *     <tr><td><code>"Grid"</code></td><td>A grid of lines in a plane.</td>
      *       <td>{@link Entities.EntityProperties-Grid|EntityProperties-Grid}</td></tr>
-     *     <tr><td><code>"Gizmo"</code></td><td>An entity with various UI-related properties.</td>
+     *     <tr><td><code>"Gizmo"</code></td><td>A gizmo intended for UI.</td>
      *       <td>{@link Entities.EntityProperties-Gizmo|EntityProperties-Gizmo}</td></tr>
      *     <tr><td><code>"Light"</code></td><td>A local lighting effect.</td>
      *       <td>{@link Entities.EntityProperties-Light|EntityProperties-Light}</td></tr>

libraries/entities/src/GrabPropertyGroup.h

@@ -41,35 +41,33 @@ static const glm::vec3 INITIAL_EQUIPPABLE_INDICATOR_OFFSET { glm::vec3(0.0f) };
 
 
 /**jsdoc
- * Grab is defined by the following properties.
+ * Grabbing behavior is defined by the following properties:
+ *
  * @typedef {object} Entities.Grab
- *
+ * @property {boolean} grabbable=true - If <code>true</code> then the entity can be grabbed.
- * @property {boolean} grabbable=true - If <code>true</code> the entity can be grabbed.
+ * @property {boolean} grabKinematic=true - If <code>true</code> then the entity will be updated in a kinematic manner when 
- * @property {boolean} grabKinematic=true - If <code>true</code> the entity is updated in a kinematic manner.
+ *     grabbed; if <code>false</code> it will be grabbed using a tractor action. A kinematic grab will make the item appear 
- *     If <code>false</code> it will be grabbed using a tractor action.  A kinematic grab will make the item appear more
+ *     more tightly held but will cause it to behave poorly when interacting with dynamic entities.
- *     tightly held, but will cause it to behave poorly when interacting with dynamic entities.
+ * @property {boolean} grabFollowsController=true - If <code>true</code> then the entity will follow the motions of the hand 
- * @property {boolean} grabFollowsController=true - If <code>true</code> the entity will follow the motions of the
+ *     controller even if the avatar's hand can't get to the implied position. This should be set <code>true</code> for tools, 
- *     hand-controller even if the avatar's hand can't get to the implied position.  This should be <code>true</code>
+ *     pens, etc. and <code>false</code> for things meant to decorate the hand.
- *     for tools, pens, etc and false for things meant to decorate the hand.
+ * @property {boolean} triggerable=false - If <code>true</code> then the entity will receive calls to trigger
- *
- * @property {boolean} triggerable=false - If <code>true</code> the entity will receive calls to trigger
  *     {@link Controller|Controller entity methods}.
- *
+ * @property {boolean} grabDelegateToParent=true - If <code>true</code> and the entity is grabbed, the grab will be transferred 
- * @property {boolean} equippable=true - If <code>true</code> the entity can be equipped.
+ *     to its parent entity if there is one; if <code>false</code>, a child entity can be grabbed and moved relative to its 
+ *     parent.
+ * @property {boolean} equippable=true - If <code>true</code> then the entity can be equipped.
  * @property {Vec3} equippableLeftPosition=0,0,0 - Positional offset from the left hand, when equipped.
  * @property {Quat} equippableLeftRotation=0,0,0,1 - Rotational offset from the left hand, when equipped.
  * @property {Vec3} equippableRightPosition=0,0,0 - Positional offset from the right hand, when equipped.
  * @property {Quat} equippableRightRotation=0,0,0,1 - Rotational offset from the right hand, when equipped.
- *
  * @property {string} equippableIndicatorURL="" - If non-empty, this model will be used to indicate that an
  *     entity is equippable, rather than the default.
- * @property {Vec3} equippableIndicatorScale=1,1,1 - If equippableIndicatorURL is non-empty, this controls the
+ * @property {Vec3} equippableIndicatorScale=1,1,1 - If <code>equippableIndicatorURL</code> is non-empty, this controls the
        scale of the displayed indicator.
- * @property {Vec3} equippableIndicatorOffset=0,0,0 - If equippableIndicatorURL is non-empty, this controls the
+ * @property {Vec3} equippableIndicatorOffset=0,0,0 - If <code>equippableIndicatorURL</code> is non-empty, this controls the
        relative offset of the displayed object from the equippable entity.
  */
-
-
 class GrabPropertyGroup : public PropertyGroup {
 public:
     // EntityItemProperty related helpers

libraries/entities/src/HazePropertyGroup.h

@@ -43,7 +43,7 @@ static const float INITIAL_KEY_LIGHT_ALTITUDE{ 200.0f };
 // FIXME: Document hazeAttenuationKeyLight, hazeKeyLightRange, and hazeKeyLightAltitude once they're working and are provided 
 // in the Create app's UI.
 /**jsdoc
- * Haze is defined by the following properties.
+ * Haze is defined by the following properties:
  * @typedef {object} Entities.Haze
  *
  * @property {number} hazeRange=1000 - The horizontal distance at which visibility is reduced to 95%; i.e., 95% of each pixel's 
@@ -56,7 +56,7 @@ static const float INITIAL_KEY_LIGHT_ALTITUDE{ 200.0f };
  *     haze color are blended 50/50.
  *
  * @property {boolean} hazeAltitudeEffect=false - If <code>true</code> then haze decreases with altitude as defined by the 
- *     entity's local coordinate system; <code>hazeBaseRef</code> and </code>hazeCeiling</code> are used.
+ *     entity's local coordinate system; <code>hazeBaseRef</code> and <code>hazeCeiling</code> are used.
  * @property {number} hazeBaseRef=0 - The y-axis value in the entity's local coordinate system at which the haze density starts 
  *     reducing with altitude.
  * @property {number} hazeCeiling=200 - The y-axis value in the entity's local coordinate system at which the haze density has 
@@ -65,9 +65,11 @@ static const float INITIAL_KEY_LIGHT_ALTITUDE{ 200.0f };
  * @property {number} hazeBackgroundBlend=0 - The proportion of the skybox image to show through the haze: <code>0.0</code> 
  *     displays no skybox image; <code>1.0</code> displays no haze.
  *
- * @property {boolean} hazeAttenuateKeyLight=false - <em>Currently not supported.</em>
+ * @property {boolean} hazeAttenuateKeyLight=false - If <code>true</code> then the haze attenuates the key light; 
- * @property {number} hazeKeyLightRange=1000 - <em>Currently not supported.</em>
+ *     <code>hazeKeyLightRange</code> and <code>hazeKeyLightAltitude</code> are used.
- * @property {number} hazeKeyLightAltitude=200 - <em>Currently not supported.</em>
+ * @property {number} hazeKeyLightRange=1000 -  The distance at which the haze attenuates the key light by 95%.
+ * @property {number} hazeKeyLightAltitude=200 - The altitude at which the haze starts attenuating the key light (i.e., the 
+ *     altitude at which the distance starts being calculated).
  */
 class HazePropertyGroup : public PropertyGroup {
 public:

libraries/entities/src/KeyLightPropertyGroup.h

@@ -28,13 +28,13 @@ class EntityTreeElementExtraEncodeData;
 class ReadBitstreamToTreeParams;
 
 /**jsdoc
- * A key light is defined by the following properties.
+ * A key light is defined by the following properties:
  * @typedef {object} Entities.KeyLight
  * @property {Color} color=255,255,255 - The color of the light.
  * @property {number} intensity=1 - The intensity of the light.
  * @property {Vec3} direction=0,-1,0 - The direction the light is shining.
  * @property {boolean} castShadows=false - If <code>true</code> then shadows are cast. Shadows are cast by avatars, plus 
- *     {@link Entities.EntityType|Model} and {@link Entities.EntityType|Shape} entities that have their 
+ *     {@link Entities.EntityProperties-Model|Model} and {@link Entities.EntityProperties-Shape|Shape} entities that have their 
  *     <code>{@link Entities.EntityProperties|canCastShadow}</code> property set to <code>true</code>.
  */
 class KeyLightPropertyGroup : public PropertyGroup {

libraries/entities/src/PolyVoxEntityItem.h

@@ -63,7 +63,7 @@ class PolyVoxEntityItem : public EntityItem {
     virtual int getOnCount() const { return 0; }
 
     /**jsdoc
-     * <p>A <code>PolyVoxSurfaceStyle</code> may be one of the following:</p>
+     * <p>The surface of a {@link Entities.EntityProperties-PolyVox|PolyVox} entity may be one of the following styles:</p>
      * <table>
      *   <thead>
      *     <tr><th>Value</th><th>Type</th><th>Description</th></tr>

libraries/entities/src/PulsePropertyGroup.h

@@ -26,19 +26,17 @@ class OctreePacketData;
 class ReadBitstreamToTreeParams;
 
 /**jsdoc
- * Pulse is defined by the following properties.
+ * A color and alpha pulse that an entity may have.
  * @typedef {object} Entities.Pulse
- *
  * @property {number} min=0 - The minimum value of the pulse multiplier.
  * @property {number} max=1 - The maximum value of the pulse multiplier.
  * @property {number} period=1 - The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from
  *     <code>min</code> to <code>max</code>, then <code>max</code> to <code>min</code> in one period.
- * @property {PulseMode} colorMode="none" - If "in", the color is pulsed in phase with the pulse period; if "out"
+ * @property {Entities.PulseMode} colorMode="none" - If "in", the color is pulsed in phase with the pulse period; if "out"
  *     the color is pulsed out of phase with the pulse period.
- * @property {PulseMode} alphaMode="none" - If "in", the alpha is pulsed in phase with the pulse period; if "out"
+ * @property {Entities.PulseMode} alphaMode="none" - If "in", the alpha is pulsed in phase with the pulse period; if "out"
  *     the alpha is pulsed out of phase with the pulse period.
  */
-
 class PulsePropertyGroup : public PropertyGroup {
 public:
     // EntityItemProperty related helpers

libraries/entities/src/RingGizmoPropertyGroup.h

@@ -25,31 +25,32 @@ class ReadBitstreamToTreeParams;
 using u8vec3Color = glm::u8vec3;
 
 /**jsdoc
- * A RingGizmo is defined by the following properties.
+ * A {@link Entities.EntityProperties-Gizmo|ring Gizmo} entity is defined by the following properties:
  * @typedef {object} Entities.RingGizmo
  *
- * @property {number} startAngle=0 - The angle at which the ring will start, in degrees.
+ * @property {number} startAngle=0 - The angle at which the ring starts, in degrees.
- * @property {number} endAngle=360 - The angle at which the ring will end, in degrees.
+ * @property {number} endAngle=360 - The angle at which the ring ends, in degrees.
- * @property {number} innerRadius=0 - The inner radius of the ring as a fraction of the total radius.  0-1.
+ * @property {number} innerRadius=0 - The inner radius of the ring as a fraction of the total radius, range <code>0.0</code> 
+ *     &mdash; <code>1.0</code>.
 
- * @property {Color} innerStartColor - The color at the inner start point of the ring.
+ * @property {Color} innerStartColor=255,255,255 - The color at the inner start point of the ring.
- * @property {Color} innerEndColor - The color at the inner end point of the ring.
+ * @property {Color} innerEndColor=255,255,255 - The color at the inner end point of the ring.
- * @property {Color} outerStartColor - The color at the outer start point of the ring.
+ * @property {Color} outerStartColor=255,255,255 - The color at the outer start point of the ring.
- * @property {Color} outerEndColor - The color at the outer end point of the ring.
+ * @property {Color} outerEndColor=255,255,255 - The color at the outer end point of the ring.
- * @property {number} innerStartAlpha=1 - The alpha at the inner start point of the ring.
+ * @property {number} innerStartAlpha=1 - The opacity at the inner start point of the ring.
- * @property {number} innerEndAlpha=1 - The alpha at the inner end point of the ring.
+ * @property {number} innerEndAlpha=1 - The opacity at the inner end point of the ring.
- * @property {number} outerStartAlpha=1 - The alpha at the outer start point of the ring.
+ * @property {number} outerStartAlpha=1 - The opacity at the outer start point of the ring.
- * @property {number} outerEndAlpha=1 - The alpha at the outer end point of the ring.
+ * @property {number} outerEndAlpha=1 - The opacity at the outer end point of the ring.
 
- * @property {boolean} hasTickMarks=false - Whether or not to render tick marks.
+ * @property {boolean} hasTickMarks=false - <code>true</code> to render tick marks, otherwise <code>false</code>.
- * @property {number} majorTickMarksAngle - The angle between major tick marks, in degrees.
+ * @property {number} majorTickMarksAngle=0 - The angle between major tick marks, in degrees.
- * @property {number} minorTickMarksAngle - The angle between minor tick marks, in degrees.
+ * @property {number} minorTickMarksAngle=0 - The angle between minor tick marks, in degrees.
- * @property {number} majorTickMarksLength - The length of the major tick marks, as a fraction of the radius. A positive value draws tick marks
+ * @property {number} majorTickMarksLength=0 - The length of the major tick marks as a fraction of the radius. A positive value 
- *     outwards from the inner radius; a negative value draws tick marks inwards from the outer radius.
+ *     draws tick marks outwards from the inner radius; a negative value draws tick marks inwards from the outer radius.
- * @property {number} minorTickMarksLength - The length of the minor tick marks, as a fraction of the radius. A positive value draws tick marks
+ * @property {number} minorTickMarksLength=0 - The length of the minor tick marks, as a fraction of the radius. A positive 
- *     outwards from the inner radius; a negative value draws tick marks inwards from the outer radius.
+ *     value draws tick marks outwards from the inner radius; a negative value draws tick marks inwards from the outer radius.
- * @property {Color} majorTickMarksColor - The color of the major tick marks.
+ * @property {Color} majorTickMarksColor=255,255,255 - The color of the major tick marks.
- * @property {Color} minorTickMarksColor - The color of the minor tick marks.
+ * @property {Color} minorTickMarksColor=255,255,255 - The color of the minor tick marks.
  */
 
 class RingGizmoPropertyGroup : public PropertyGroup {

libraries/entities/src/ShapeEntityItem.cpp

@@ -22,8 +22,8 @@
 namespace entity {
 
     /**jsdoc
-     * <p>A <code>Shape</code>, <code>Box</code>, or <code>Sphere</code> {@link Entities.EntityType|EntityType} may display as 
+     * <p>A <code>"Shape"</code>, <code>"Box"</code>, or <code>"Sphere"</code> {@link Entities.EntityType|EntityType} may 
-     * one of the following geometrical shapes:</p>
+     * display as one of the following geometrical shapes:</p>
      * <table>
      *   <thead>
      *     <tr><th>Value</th><th>Dimensions</th><th>Notes</th></tr>

libraries/entities/src/SkyboxPropertyGroup.h

@@ -30,7 +30,7 @@ class EntityTreeElementExtraEncodeData;
 class ReadBitstreamToTreeParams;
 
 /**jsdoc
- * A skybox is defined by the following properties.
+ * A skybox is defined by the following properties:
  * @typedef {object} Entities.Skybox
  * @property {Color} color=0,0,0 - Sets the color of the sky if <code>url</code> is <code>""</code>, otherwise modifies the
  *     color of the cube map image.

libraries/material-networking/src/material-networking/MaterialCache.cpp

@@ -70,10 +70,10 @@ bool NetworkMaterialResource::parseJSONColor(const QJsonValue& array, glm::vec3&
 }
 
 /**jsdoc
- * A material or set of materials such as may be used by a {@link Entities.EntityType|Material} entity.
+ * A material or set of materials used by a {@link Entities.EntityType|Material entity}.
- * @typedef {object} MaterialResource
+ * @typedef {object} Entities.MaterialResource
  * @property {number} materialVersion=1 - The version of the material. <em>Currently not used.</em>
- * @property {Material|Material[]} materials - The details of the material or materials.
+ * @property {Entities.Material|Entities.Material[]} materials - The details of the material or materials.
  */
 NetworkMaterialResource::ParsedMaterials NetworkMaterialResource::parseJSONMaterials(const QJsonDocument& materialJSON, const QUrl& baseUrl) {
     ParsedMaterials toReturn;
@@ -109,60 +109,72 @@ NetworkMaterialResource::ParsedMaterials NetworkMaterialResource::parseJSONMater
 }
 
 /**jsdoc
- * A material such as may be used by a {@link Entities.EntityType|Material} entity.
+ * A material used in a {@link Entities.MaterialResource|MaterialResource}.
- * @typedef {object} Material
+ * @typedef {object} Entities.Material
  * @property {string} model="hifi_pbr" - Different material models support different properties and rendering modes.
- *     Supported models are: "hifi_pbr"
+ *     Supported models are: <code>"hifi_pbr"</code>.
  * @property {string} name="" - A name for the material. Supported by all material models.
- * @property {Color|RGBS|string} emissive - The emissive color, i.e., the color that the material emits. A {@link Color} value
+ * @property {ColorFloat|RGBS|string} emissive - The emissive color, i.e., the color that the material emits. A 
- *     is treated as sRGB. A {@link RGBS} value can be either RGB or sRGB.  Set to <code>"fallthrough"</code> to fallthrough to
+ *     {@link ColorFloat} value is treated as sRGB and must have component values in the range <code>0.0</code> &mdash; 
- *     the material below.  "hifi_pbr" model only.
+ *     <code>1.0</code>. A {@link RGBS} value can be either RGB or sRGB. 
- * @property {number|string} opacity=1.0 - The opacity, <code>0.0</code> &ndash; <code>1.0</code>.  Set to <code>"fallthrough"</code> to fallthrough to
+ *     Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
- *     the material below.  "hifi_pbr" model only.
+ * @property {number|string} opacity=1.0 - The opacity, range <code>0.0</code> &ndash; <code>1.0</code>. 
- * @property {boolean|string} unlit=false - If <code>true</code>, the material is not lit.  Set to <code>"fallthrough"</code> to fallthrough to
+ *     Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
- *     the material below.  "hifi_pbr" model only.
+ * @property {boolean|string} unlit=false - If <code>true</code>, the material is not lit, otherwise it is. 
- * @property {Color|RGBS|string} albedo - The albedo color. A {@link Color} value is treated as sRGB. A {@link RGBS} value can
+ *     Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
- *     be either RGB or sRGB.  Set to <code>"fallthrough"</code> to fallthrough to the material below.  Set to <code>"fallthrough"</code> to fallthrough to
+ * @property {ColorFloat|RGBS|string} albedo - The albedo color. A {@link ColorFloat} value is treated as sRGB and must have 
- *     the material below.  "hifi_pbr" model only.
+ *     component values in the range <code>0.0</code> &mdash; <code>1.0</code>. A {@link RGBS} value can be either RGB or sRGB. 
- * @property {number|string} roughness - The roughness, <code>0.0</code> &ndash; <code>1.0</code>.  Set to <code>"fallthrough"</code> to fallthrough to
+ *     Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
- *     the material below.  "hifi_pbr" model only.
+ * @property {number|string} roughness - The roughness, range <code>0.0</code> &ndash; <code>1.0</code>. 
- * @property {number|string} metallic - The metallicness, <code>0.0</code> &ndash; <code>1.0</code>.  Set to <code>"fallthrough"</code> to fallthrough to
+ *     Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
- *     the material below.  "hifi_pbr" model only.
+ * @property {number|string} metallic - The metallicness, range <code>0.0</code> &ndash; <code>1.0</code>. 
- * @property {number|string} scattering - The scattering, <code>0.0</code> &ndash; <code>1.0</code>.  Set to <code>"fallthrough"</code> to fallthrough to
+ *     Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
- *     the material below.  "hifi_pbr" model only.
+ * @property {number|string} scattering - The scattering, range <code>0.0</code> &ndash; <code>1.0</code>. 
- * @property {string} emissiveMap - URL of emissive texture image.  Set to <code>"fallthrough"</code> to fallthrough to
+ *     Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
- *     the material below.  "hifi_pbr" model only.
+ * @property {string} emissiveMap - The URL of the emissive texture image. 
- * @property {string} albedoMap - URL of albedo texture image.  Set to <code>"fallthrough"</code> to fallthrough to
+ *     Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
- *     the material below.  "hifi_pbr" model only.
+ * @property {string} albedoMap - The URL of the albedo texture image. 
- * @property {string} opacityMap - URL of opacity texture image. Set value the same as the <code>albedoMap</code> value for 
+ *     Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
- *     transparency.  "hifi_pbr" model only.
+ * @property {string} opacityMap - The URL of the opacity texture image. Set the value the same as the <code>albedoMap</code> 
- * @property {string} roughnessMap - URL of roughness texture image. Can use this or <code>glossMap</code>, but not both.  Set to <code>"fallthrough"</code>
+ *     value for transparency. 
- *     to fallthrough to the material below.  "hifi_pbr" model only.
+ *     <code>"hifi_pbr"</code> model only.
- * @property {string} glossMap - URL of gloss texture image. Can use this or <code>roughnessMap</code>, but not both.  Set to <code>"fallthrough"</code>
+ * @property {string} roughnessMap - The URL of the roughness texture image. You can use this or <code>glossMap</code>, but not 
- *     to fallthrough to the material below.  "hifi_pbr" model only.
+ *     both. 
- * @property {string} metallicMap - URL of metallic texture image. Can use this or <code>specularMap</code>, but not both.  Set to <code>"fallthrough"</code>
+ *     Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
- *     to fallthrough to the material below.  "hifi_pbr" model only.
+ * @property {string} glossMap - The URL of the gloss texture image. You can use this or <code>roughnessMap</code>, but not 
- * @property {string} specularMap - URL of specular texture image. Can use this or <code>metallicMap</code>, but not both.  Set to <code>"fallthrough"</code>
+ *     both. 
- *     to fallthrough to the material below.  "hifi_pbr" model only.
+ *     Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
- * @property {string} normalMap - URL of normal texture image. Can use this or <code>bumpMap</code>, but not both.  Set to <code>"fallthrough"</code>
+ * @property {string} metallicMap - The URL of the metallic texture image. You can use this or <code>specularMap</code>, but 
- *     to fallthrough to the material below.  "hifi_pbr" model only.
+ *     not both. 
- * @property {string} bumpMap - URL of bump texture image. Can use this or <code>normalMap</code>, but not both.  Set to <code>"fallthrough"</code>
+ *     Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
- *     to fallthrough to the material below.  "hifi_pbr" model only.
+ * @property {string} specularMap - The URL of the specular texture image. You can use this or <code>metallicMap</code>, but 
- * @property {string} occlusionMap - URL of occlusion texture image.  Set to <code>"fallthrough"</code> to fallthrough to the material below.  "hifi_pbr" model only.
+ *     not both. 
- * @property {string} scatteringMap - URL of scattering texture image. Only used if <code>normalMap</code> or 
+ *     Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
- *     <code>bumpMap</code> is specified.  Set to <code>"fallthrough"</code> to fallthrough to the material below.  "hifi_pbr" model only.
+ * @property {string} normalMap - The URL of the normal texture image. You can use this or <code>bumpMap</code>, but not both. 
- * @property {string} lightMap - URL of light map texture image. <em>Currently not used.</em>.  Set to <code>"fallthrough"</code>
+ *     Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
- *     to fallthrough to the material below.  "hifi_pbr" model only.
+ * @property {string} bumpMap - The URL of the bump texture image. You can use this or <code>normalMap</code>, but not both. 
- * @property {string} texCoordTransform0 - The transform to use for all of the maps besides occlusionMap and lightMap.  Currently unused.  Set to
+ *     Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
- *     <code>"fallthrough"</code> to fallthrough to the material below.  "hifi_pbr" model only.
+ * @property {string} occlusionMap - The URL of the occlusion texture image. 
- * @property {string} texCoordTransform1 - The transform to use for occlusionMap and lightMap.  Currently unused.  Set to <code>"fallthrough"</code>
+ *     Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
- *     to fallthrough to the material below.  "hifi_pbr" model only.
+ * @property {string} scatteringMap - The URL of the scattering texture image. Only used if <code>normalMap</code> or 
- * @property {string} lightmapParams - Parameters for controlling how lightMap is used.  Currently unused.  Set to <code>"fallthrough"</code>
+ *     <code>bumpMap</code> is specified. 
- *     to fallthrough to the material below.  "hifi_pbr" model only.
+ *     Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
- * @property {string} materialParams - Parameters for controlling the material projection and repition.  Currently unused.  Set to <code>"fallthrough"</code>
+ * @property {string} lightMap - The URL of the light map texture image. 
- *     to fallthrough to the material below.  "hifi_pbr" model only.
+ *     Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
- * @property {bool} defaultFallthrough=false - If <code>true</code>, all properties will fallthrough to the material below unless they are set.  If
+ * @property {Mat4|string} texCoordTransform0 - The transform to use for all of the maps apart from <code>occlusionMap</code> 
- *     <code>false</code>, they will respect the individual properties' fallthrough state.  "hifi_pbr" model only.
+ *     and <code>lightMap</code>. 
+ *     Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
+ * @property {Mat4|string} texCoordTransform1 - The transform to use for <code>occlusionMap</code> and <code>lightMap</code>. 
+ *     Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
+ * @property {string} lightmapParams - Parameters for controlling how lightMap is used. 
+ *     Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only. 
+ *     <p><em>Currently not used.</em></p>
+ * @property {string} materialParams - Parameters for controlling the material projection and repetition. 
+ *     Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only. 
+ *     <p><em>Currently not used.</em></p>
+ * @property {boolean} defaultFallthrough=false - If <code>true</code>, all properties fall through to the material below 
+ *     unless they are set. If <code>false</code>, they respect their individual fall-through setting. <code>"hifi_pbr"</code> 
+ *     model only.
  */
 // Note: See MaterialEntityItem.h for default values used in practice.
 std::pair<std::string, std::shared_ptr<NetworkMaterial>> NetworkMaterialResource::parseJSONMaterial(const QJsonObject& materialJSON, const QUrl& baseUrl) {
@@ -399,7 +411,7 @@ std::pair<std::string, std::shared_ptr<NetworkMaterial>> NetworkMaterialResource
                         material->setPropertyDoesFallthrough(graphics::Material::ExtraFlagBit::LIGHTMAP_PARAMS);
                     }
                 }
-                // TODO: implement lightmapParams
+                // TODO: implement lightmapParams and update JSDoc
             } else if (key == "materialParams") {
                 auto value = materialJSON.value(key);
                 if (value.isString()) {
@@ -408,7 +420,7 @@ std::pair<std::string, std::shared_ptr<NetworkMaterial>> NetworkMaterialResource
                         material->setPropertyDoesFallthrough(graphics::Material::ExtraFlagBit::MATERIAL_PARAMS);
                     }
                 }
-                // TODO: implement materialParams
+                // TODO: implement materialParams and update JSDoc
             } else if (key == "defaultFallthrough") {
                 auto value = materialJSON.value(key);
                 if (value.isBool()) {

libraries/octree/src/OctreeScriptingInterface.h

@@ -37,7 +37,7 @@ private slots:
 public slots:
 
     /**jsdoc
-     * Set the maximum number of entity packets that the client can send per second.
+     * Sets the maximum number of entity packets that the client can send per second.
      * @function Entities.setPacketsPerSecond
      * @param {number} packetsPerSecond - Integer maximum number of entity packets that the client can send per second.
      */
@@ -45,7 +45,7 @@ public slots:
     void setPacketsPerSecond(int packetsPerSecond) { return _packetSender->setPacketsPerSecond(packetsPerSecond); }
 
     /**jsdoc
-     * Get the maximum number of entity packets that the client can send per second.
+     * Gets the maximum number of entity packets that the client can send per second.
      * @function Entities.getPacketsPerSecond
      * @returns {number} Integer maximum number of entity packets that the client can send per second.
      */
@@ -53,7 +53,7 @@ public slots:
     int getPacketsPerSecond() const  { return _packetSender->getPacketsPerSecond(); }
 
     /**jsdoc
-     * Check whether servers exist for the client to send entity packets to, i.e., whether you are connected to a domain and 
+     * Checks whether servers exist for the client to send entity packets to, i.e., whether you are connected to a domain and
      * its entity server is working.
      * @function Entities.serversExist
      * @returns {boolean} <code>true</code> if servers exist for the client to send entity packets to, otherwise 
@@ -63,7 +63,7 @@ public slots:
     bool serversExist() const { return _packetSender->serversExist(); }
 
     /**jsdoc
-     * Check whether the client has entity packets waiting to be sent.
+     * Checks whether the client has entity packets waiting to be sent.
      * @function Entities.hasPacketsToSend
      * @returns {boolean} <code>true</code> if the client has entity packets waiting to be sent, otherwise <code>false</code>.
      */
@@ -71,7 +71,7 @@ public slots:
     bool hasPacketsToSend() const { return _packetSender->hasPacketsToSend(); }
 
     /**jsdoc
-     * Get the number of entity packets the client has waiting to be sent.
+     * Gets the number of entity packets the client has waiting to be sent.
      * @function Entities.packetsToSendCount
      * @returns {number} Integer number of entity packets the client has waiting to be sent.
      */
@@ -79,7 +79,7 @@ public slots:
     int packetsToSendCount() const { return (int)_packetSender->packetsToSendCount(); }
 
     /**jsdoc
-     * Get the entity packets per second send rate of the client over its lifetime.
+     * Gets the entity packets per second send rate of the client over its lifetime.
      * @function Entities.getLifetimePPS
      * @returns {number} Entity packets per second send rate of the client over its lifetime.
      */
@@ -87,7 +87,7 @@ public slots:
     float getLifetimePPS() const { return _packetSender->getLifetimePPS(); }
 
     /**jsdoc
-     * Get the entity bytes per second send rate of the client over its lifetime.
+     * Gets the entity bytes per second send rate of the client over its lifetime.
      * @function Entities.getLifetimeBPS
      * @returns {number} Entity bytes per second send rate of the client over its lifetime.
      */
@@ -95,7 +95,7 @@ public slots:
     float getLifetimeBPS() const { return _packetSender->getLifetimeBPS(); }
 
     /**jsdoc
-     * Get the entity packets per second queued rate of the client over its lifetime.
+     * Gets the entity packets per second queued rate of the client over its lifetime.
      * @function Entities.getLifetimePPSQueued
      * @returns {number} Entity packets per second queued rate of the client over its lifetime.
      */
@@ -103,7 +103,7 @@ public slots:
     float getLifetimePPSQueued() const  { return _packetSender->getLifetimePPSQueued(); }
 
     /**jsdoc
-     * Get the entity bytes per second queued rate of the client over its lifetime.
+     * Gets the entity bytes per second queued rate of the client over its lifetime.
      * @function Entities.getLifetimeBPSQueued
      * @returns {number} Entity bytes per second queued rate of the client over its lifetime.
      */
@@ -111,7 +111,7 @@ public slots:
     float getLifetimeBPSQueued() const { return _packetSender->getLifetimeBPSQueued(); }
 
     /**jsdoc
-     * Get the lifetime of the client from the first entity packet sent until now, in microseconds.
+     * Gets the lifetime of the client from the first entity packet sent until now, in microseconds.
      * @function Entities.getLifetimeInUsecs
      * @returns {number} Lifetime of the client from the first entity packet sent until now, in microseconds.
      */
@@ -119,7 +119,7 @@ public slots:
     long long unsigned int getLifetimeInUsecs() const { return _packetSender->getLifetimeInUsecs(); }
 
     /**jsdoc
-     * Get the lifetime of the client from the first entity packet sent until now, in seconds.
+     * Gets the lifetime of the client from the first entity packet sent until now, in seconds.
      * @function Entities.getLifetimeInSeconds
      * @returns {number} Lifetime of the client from the first entity packet sent until now, in seconds.
      */
@@ -127,7 +127,7 @@ public slots:
     float getLifetimeInSeconds() const { return _packetSender->getLifetimeInSeconds(); }
 
     /**jsdoc
-     * Get the total number of entity packets sent by the client over its lifetime.
+     * Gets the total number of entity packets sent by the client over its lifetime.
      * @function Entities.getLifetimePacketsSent
      * @returns {number} The total number of entity packets sent by the client over its lifetime.
      */
@@ -135,7 +135,7 @@ public slots:
     long long unsigned int getLifetimePacketsSent() const { return _packetSender->getLifetimePacketsSent(); }
 
     /**jsdoc
-     * Get the total bytes of entity packets sent by the client over its lifetime.
+     * Gets the total bytes of entity packets sent by the client over its lifetime.
      * @function Entities.getLifetimeBytesSent
      * @returns {number} The total bytes of entity packets sent by the client over its lifetime.
      */
@@ -143,7 +143,7 @@ public slots:
     long long unsigned int getLifetimeBytesSent() const { return _packetSender->getLifetimeBytesSent(); }
 
     /**jsdoc
-     * Get the total number of entity packets queued by the client over its lifetime.
+     * Gets the total number of entity packets queued by the client over its lifetime.
      * @function Entities.getLifetimePacketsQueued
      * @returns {number} The total number of entity packets queued by the client over its lifetime.
      */
@@ -151,7 +151,7 @@ public slots:
     long long unsigned int getLifetimePacketsQueued() const { return _packetSender->getLifetimePacketsQueued(); }
 
     /**jsdoc
-     * Get the total bytes of entity packets queued by the client over its lifetime.
+     * Gets the total bytes of entity packets queued by the client over its lifetime.
      * @function Entities.getLifetimeBytesQueued
      * @returns {number} The total bytes of entity packets queued by the client over its lifetime.
      */

libraries/physics/src/ObjectActionOffset.cpp

@@ -145,7 +145,7 @@ bool ObjectActionOffset::updateArguments(QVariantMap arguments) {
 /**jsdoc
  * The <code>"offset"</code> {@link Entities.ActionType|ActionType} moves an entity so that it is a set distance away from a 
  * target point.
- * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}.
+ * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}:
  *
  * @typedef {object} Entities.ActionArguments-Offset
  * @property {Vec3} pointToOffsetFrom=0,0,0 - The target point to offset the entity from.

libraries/physics/src/ObjectActionTractor.cpp

@@ -341,15 +341,15 @@ bool ObjectActionTractor::updateArguments(QVariantMap arguments) {
 /**jsdoc
  * The <code>"tractor"</code> {@link Entities.ActionType|ActionType} moves and rotates an entity to a target position and
  * orientation, optionally relative to another entity.
- * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}.
+ * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}:
  *
  * @typedef {object} Entities.ActionArguments-Tractor
+ * @property {Uuid} otherID=null - If an entity ID, the <code>targetPosition</code> and <code>targetRotation</code> are
+ *     relative to the entity's position and rotation.
+ * @property {Uuid} otherJointIndex=null - If a joint index in the <code>otherID</code> entity, the <code>targetPosition</code> 
+ *     and <code>targetRotation</code> are relative to the entity joint's position and rotation.
  * @property {Vec3} targetPosition=0,0,0 - The target position.
  * @property {Quat} targetRotation=0,0,0,1 - The target rotation.
- * @property {Uuid} otherID=null - If an entity ID, the <code>targetPosition</code> and <code>targetRotation</code> are
- *     relative to this entity's position and rotation.
- * @property {Uuid} otherJointIndex=null - If an entity JointIndex, the <code>targetPosition</code> and
- *     <code>targetRotation</code> are relative to this entity's joint's position and rotation.
  * @property {number} linearTimeScale=3.4e+38 - Controls how long it takes for the entity's position to catch up with the
  *     target position. The value is the time for the action to catch up to 1/e = 0.368 of the target value, where the action
  *     is applied using an exponential decay.

libraries/physics/src/ObjectActionTravelOriented.cpp

@@ -152,7 +152,7 @@ bool ObjectActionTravelOriented::updateArguments(QVariantMap arguments) {
 /**jsdoc
  * The <code>"travel-oriented"</code> {@link Entities.ActionType|ActionType} orients an entity to align with its direction of 
  * travel.
- * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}.
+ * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}:
  *
  * @typedef {object} Entities.ActionArguments-TravelOriented
  * @property {Vec3} forward=0,0,0 - The axis of the entity to align with the entity's direction of travel.

libraries/physics/src/ObjectConstraintBallSocket.cpp

@@ -183,11 +183,11 @@ bool ObjectConstraintBallSocket::updateArguments(QVariantMap arguments) {
 
 /**jsdoc
  * The <code>"ball-socket"</code> {@link Entities.ActionType|ActionType} connects two entities with a ball and socket joint. 
- * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}.
+ * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}:
  *
  * @typedef {object} Entities.ActionArguments-BallSocket
- * @property {Vec3} pivot=0,0,0 - The local offset of the joint relative to the entity's position.
  * @property {Uuid} otherEntityID=null - The ID of the other entity that is connected to the joint.
+ * @property {Vec3} pivot=0,0,0 - The local offset of the joint relative to the entity's position.
  * @property {Vec3} otherPivot=0,0,0 - The local offset of the joint relative to the other entity's position.
  */
 QVariantMap ObjectConstraintBallSocket::getArguments() {

libraries/physics/src/ObjectConstraintConeTwist.cpp

@@ -264,17 +264,18 @@ bool ObjectConstraintConeTwist::updateArguments(QVariantMap arguments) {
 /**jsdoc
  * The <code>"cone-twist"</code> {@link Entities.ActionType|ActionType} connects two entities with a joint that can move 
  * through a cone and can twist.
- * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}.
+ * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}:
  *
  * @typedef {object} Entities.ActionArguments-ConeTwist
+ * @property {Uuid} otherEntityID=null - The ID of the other entity that is connected to the joint.
  * @property {Vec3} pivot=0,0,0 - The local offset of the joint relative to the entity's position.
  * @property {Vec3} axis=1,0,0 - The axis of the entity that moves through the cone. Must be a non-zero vector.
- * @property {Uuid} otherEntityID=null - The ID of the other entity that is connected to the joint.
  * @property {Vec3} otherPivot=0,0,0 - The local offset of the joint relative to the other entity's position.
  * @property {Vec3} otherAxis=1,0,0 - The axis of the other entity that moves through the cone. Must be a non-zero vector.
- * @property {number} swingSpan1=6.238 - The angle through which the joint can move in one axis of the cone, in radians.
+ * @property {number} swingSpan1=2*Math.PI - The angle through which the joint can move in one axis of the cone, in radians.
- * @property {number} swingSpan2=6.238 - The angle through which the joint can move in the other axis of the cone, in radians.
+ * @property {number} swingSpan2=2*Math.PI - The angle through which the joint can move in the other axis of the cone, in 
- * @property {number} twistSpan=6.238 - The angle through with the joint can twist, in radians.
+ *     radians.
+ * @property {number} twistSpan=2*Math.PI - The angle through with the joint can twist, in radians.
  */
 QVariantMap ObjectConstraintConeTwist::getArguments() {
     QVariantMap arguments = ObjectDynamic::getArguments();

libraries/physics/src/ObjectConstraintHinge.cpp

@@ -248,18 +248,19 @@ bool ObjectConstraintHinge::updateArguments(QVariantMap arguments) {
 /**jsdoc
  * The <code>"hinge"</code> {@link Entities.ActionType|ActionType} lets an entity pivot about an axis or connects two entities
  * with a hinge joint.
- * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}.
+ * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}:
  *
  * @typedef {object} Entities.ActionArguments-Hinge
+ * @property {Uuid} otherEntityID=null - The ID of the other entity that is connected to the joint, if any. If none is
+ *     specified then the first entity simply pivots about its specified <code>axis</code>.
  * @property {Vec3} pivot=0,0,0 - The local offset of the joint relative to the entity's position.
  * @property {Vec3} axis=1,0,0 - The axis of the entity that it pivots about. Must be a non-zero vector.
- * @property {Uuid} otherEntityID=null - The ID of the other entity that is connected to the joint, if any. If none is 
- *     specified then the first entity simply pivots about its specified <code>axis</code>.
  * @property {Vec3} otherPivot=0,0,0 - The local offset of the joint relative to the other entity's position.
  * @property {Vec3} otherAxis=1,0,0 - The axis of the other entity that it pivots about. Must be a non-zero vector.
- * @property {number} low=-6.283 - The most negative angle that the hinge can take, in radians.
+ * @property {number} low=-2*Math.PI - The most negative angle that the hinge can take, in radians.
- * @property {number} high=6.283 - The most positive angle that the hinge can take, in radians.
+ * @property {number} high=2*Math.PI - The most positive angle that the hinge can take, in radians.
- * @property {number} angle=0 - The current angle of the hinge. <em>Read-only.</em>
+ * @property {number} angle=0 - The current angle of the hinge, in radians, range <code>-Math.PI</code> &ndash; 
+ *     <code>Math.PI</code>. <em>Read-only.</em>
  */
 QVariantMap ObjectConstraintHinge::getArguments() {
     QVariantMap arguments = ObjectDynamic::getArguments();

libraries/physics/src/ObjectConstraintSlider.cpp

@@ -264,27 +264,27 @@ bool ObjectConstraintSlider::updateArguments(QVariantMap arguments) {
 /**jsdoc
  * The <code>"slider"</code> {@link Entities.ActionType|ActionType} lets an entity slide and rotate along an axis, or connects 
  * two entities that slide and rotate along a shared axis.
- * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}.
+ * It has arguments in addition to the common {@link Entities.ActionArguments|ActionArguments}:
  *
  * @typedef {object} Entities.ActionArguments-Slider
+ * @property {Uuid} otherEntityID=null - The ID of the other entity that is connected to the joint, if any. If none is
+ *     specified then the first entity simply slides and rotates about its specified <code>axis</code>.
  * @property {Vec3} point=0,0,0 - The local position of a point in the entity that slides along the axis.
  * @property {Vec3} axis=1,0,0 - The axis of the entity that slides along the joint. Must be a non-zero vector.
- * @property {Uuid} otherEntityID=null - The ID of the other entity that is connected to the joint, if any. If non is 
- *     specified then the first entity simply slides and rotates about its specified <code>axis</code>.
  * @property {Vec3} otherPoint=0,0,0 - The local position of a point in the other entity that slides along the axis.
- * @property {Vec3} axis=1,0,0 - The axis of the other entity that slides along the joint. Must be a non-zero vector.
+ * @property {Vec3} otherAxis=1,0,0 - The axis of the other entity that slides along the joint. Must be a non-zero vector.
  * @property {number} linearLow=1.17e-38 - The most negative linear offset from the entity's initial point that the entity can 
  *     have along the slider.
  * @property {number} linearHigh=3.40e+38 - The most positive linear offset from the entity's initial point that the entity can 
  *     have along the slider. 
- * @property {number} angularLow=-6.283 - The most negative angle that the entity can rotate about the axis if the action 
+ * @property {number} angularLow=-2*Math.PI - The most negative angle that the entity can rotate about the axis if the action 
  *     involves only one entity, otherwise the most negative angle the rotation can be between the two entities. In radians.
- * @property {number} angularHigh=6.283 - The most positive angle that the entity can rotate about the axis if the action 
+ * @property {number} angularHigh=Math.PI - The most positive angle that the entity can rotate about the axis if the action 
  *     involves only one entity, otherwise the most positive angle the rotation can be between the two entities. In radians.
  * @property {number} linearPosition=0 - The current linear offset the entity is from its initial point if the action involves 
  *     only one entity, otherwise the linear offset between the two entities' action points. <em>Read-only.</em>
  * @property {number} angularPosition=0 - The current angular offset of the entity from its initial rotation if the action 
- *     involves only one entity, otherwise the angular offset between the two entities. <em>Read-only.</em>
+ *     involves only one entity, otherwise the angular offset between the two entities. In radians. <em>Read-only.</em>
  */
 QVariantMap ObjectConstraintSlider::getArguments() {
     QVariantMap arguments = ObjectDynamic::getArguments();

libraries/physics/src/ObjectDynamic.cpp

@@ -94,36 +94,36 @@ bool ObjectDynamic::updateArguments(QVariantMap arguments) {
 }
 
 /**jsdoc
-* Different entity action types have different arguments: some common to all actions (listed below) and some specific to each 
+ * Different entity action types have different arguments: some common to all actions (listed in the table) and some specific 
-* {@link Entities.ActionType|ActionType} (linked to below). The arguments are accessed as an object of property names and 
+ * to each {@link Entities.ActionType|ActionType} (linked to below). The arguments are accessed as an object of property names 
-* values.
+ * and values.
-*
+ *
-* @typedef {object} Entities.ActionArguments
+ * @typedef {object} Entities.ActionArguments
-* @property {Entities.ActionType} type - The type of action.
+ * @property {Entities.ActionType} type - The type of action.
-* @property {string} tag="" - A string that a script can use for its own purposes.
+ * @property {string} tag="" - A string that a script can use for its own purposes.
-* @property {number} ttl=0 - How long the action should exist, in seconds, before it is automatically deleted. A value of 
+ * @property {number} ttl=0 - How long the action should exist, in seconds, before it is automatically deleted. A value of 
-*     <code>0</code> means that the action should not be deleted.
+ *     <code>0</code> means that the action should not be deleted.
-* @property {boolean} isMine=true - Is <code>true</code> if you created the action during your current Interface session, 
+ * @property {boolean} isMine=true - Is <code>true</code> if the action was created during the current client session, 
-*     <code>false</code> otherwise. <em>Read-only.</em>
+ *     <code>false</code> otherwise. <em>Read-only.</em>
-* @property {boolean} ::no-motion-state - Is present when the entity hasn't been registered with the physics engine yet (e.g., 
+ * @property {boolean} ::no-motion-state - Is present when the entity hasn't been registered with the physics engine yet (e.g., 
-*     if the action hasn't been properly configured), otherwise <code>undefined</code>. <em>Read-only.</em>
+ *     if the action hasn't been properly configured), otherwise <code>undefined</code>. <em>Read-only.</em>
-* @property {boolean} ::active - Is <code>true</code> when the action is modifying the entity's motion, <code>false</code> 
+ * @property {boolean} ::active - Is <code>true</code> when the action is modifying the entity's motion, <code>false</code> 
-*     otherwise. Is present once the entity has been registered with the physics engine, otherwise <code>undefined</code>. 
+ *     otherwise. Is present once the entity has been registered with the physics engine, otherwise <code>undefined</code>. 
-*     <em>Read-only.</em>
+ *     <em>Read-only.</em>
-* @property {Entities.PhysicsMotionType} ::motion-type - How the entity moves with the action. Is present once the entity has 
+ * @property {Entities.PhysicsMotionType} ::motion-type - How the entity moves with the action. Is present once the entity has 
-*     been registered with the physics engine, otherwise <code>undefined</code>. <em>Read-only.</em>
+ *     been registered with the physics engine, otherwise <code>undefined</code>. <em>Read-only.</em>
-*
+ *
-* @see The different action types have additional arguments as follows:
+ * @comment The different action types have additional arguments as follows:
-* @see {@link Entities.ActionArguments-FarGrab|ActionArguments-FarGrab}
+ * @see {@link Entities.ActionArguments-FarGrab|ActionArguments-FarGrab}
-* @see {@link Entities.ActionArguments-Hold|ActionArguments-Hold}
+ * @see {@link Entities.ActionArguments-Hold|ActionArguments-Hold}
-* @see {@link Entities.ActionArguments-Offset|ActionArguments-Offset}
+ * @see {@link Entities.ActionArguments-Offset|ActionArguments-Offset}
-* @see {@link Entities.ActionArguments-Tractor|ActionArguments-Tractor}
+ * @see {@link Entities.ActionArguments-Tractor|ActionArguments-Tractor}
-* @see {@link Entities.ActionArguments-TravelOriented|ActionArguments-TravelOriented}
+ * @see {@link Entities.ActionArguments-TravelOriented|ActionArguments-TravelOriented}
-* @see {@link Entities.ActionArguments-Hinge|ActionArguments-Hinge}
+ * @see {@link Entities.ActionArguments-Hinge|ActionArguments-Hinge}
-* @see {@link Entities.ActionArguments-Slider|ActionArguments-Slider}
+ * @see {@link Entities.ActionArguments-Slider|ActionArguments-Slider}
-* @see {@link Entities.ActionArguments-ConeTwist|ActionArguments-ConeTwist}
+ * @see {@link Entities.ActionArguments-ConeTwist|ActionArguments-ConeTwist}
-* @see {@link Entities.ActionArguments-BallSocket|ActionArguments-BallSocket}
+ * @see {@link Entities.ActionArguments-BallSocket|ActionArguments-BallSocket}
-*/
+ */
 // Note: The "type" property is set in EntityItem::getActionArguments().
 QVariantMap ObjectDynamic::getArguments() {
     QVariantMap arguments;

libraries/script-engine/src/ScriptEngine.cpp

@@ -2205,6 +2205,7 @@ void ScriptEngine::loadEntityScript(const EntityItemID& entityID, const QString&
  *     lifetime: 300  // Delete after 5 minutes.
  * });
  */
+// The JSDoc is for the callEntityScriptMethod() call in this method.
 // since all of these operations can be asynch we will always do the actual work in the response handler
 // for the download
 void ScriptEngine::entityScriptContentAvailable(const EntityItemID& entityID, const QString& scriptOrURL, const QString& contents, bool isURL, bool success , const QString& status) {
@@ -2389,8 +2390,10 @@ void ScriptEngine::entityScriptContentAvailable(const EntityItemID& entityID, co
  * <p>Note: Can only be connected to via <code>this.unoad = function () { ... }</code> in the entity script.</p>
  * <table><tr><th>Available in:</th><td>Client Entity Scripts</td><td>Server Entity Scripts</td></tr></table>
  * @function Entities.unload
+ * @param {Uuid} entityID - The ID of the entity that the script is running in.
  * @returns {Signal}
  */
+// The JSDoc is for the callEntityScriptMethod() call in this method.
 void ScriptEngine::unloadEntityScript(const EntityItemID& entityID, bool shouldRemoveFromMap) {
     if (QThread::currentThread() != thread()) {
 #ifdef THREAD_DEBUGGING

libraries/script-engine/src/ScriptEngine.h

@@ -318,6 +318,7 @@ public:
 
     /**jsdoc
      * Adds a function to the list of functions called when an entity event occurs on a particular entity.
+     * <p>See also, the {@link Entities} API.</p>
      * @function Script.addEventHandler
      * @param {Uuid} entityID - The ID of the entity.
      * @param {Script.EntityEvent} eventName - The name of the entity event.
@@ -341,6 +342,7 @@ public:
 
     /**jsdoc
      * Removes a function from the list of functions called when an entity event occurs on a particular entity.
+     * <p>See also, the {@link Entities} API.</p>
      * @function Script.removeEventHandler
      * @param {Uuid} entityID - The ID of the entity.
      * @param {Script.EntityEvent} eventName - The name of the entity event.

libraries/shared/src/BillboardMode.h

@@ -21,7 +21,7 @@
  *     <tr><td><code>"none"</code></td><td>The entity will not be billboarded.</td></tr>
  *     <tr><td><code>"yaw"</code></td><td>The entity will yaw, but not pitch, to face the camera. Its actual rotation will be 
  *       ignored.</td></tr>
- *     <tr><td><code>"full"</code></td><td>The entity will be billboarded to face the camera. Its actual rotation will be 
+ *     <tr><td><code>"full"</code></td><td>The entity will yaw and pitch to face the camera. Its actual rotation will be 
  *       ignored.</td></tr>
  *   </tbody>
  * </table>

libraries/shared/src/ComponentMode.cpp

@@ -8,6 +8,22 @@
 
 #include "ComponentMode.h"
 
+/**jsdoc
+ * <p>How an effect is applied in a {@link Entities.EntityProperties-Zone|Zone} entity.</p>
+ * <table>
+ *   <thead>
+ *     <tr><th>Value</th><th>Description</th></tr>
+ *   </thead>
+ *   <tbody>
+ *     <tr><td><code>"inherit"</code></td><td>The effect from any enclosing zone continues into this zone.</td></tr>
+ *     <tr><td><code>"disabled"</code></td><td>The effect &mdash; from any enclosing zone and this zone &mdash; is disabled in 
+ *       this zone.</td></tr>
+ *     <tr><td><code>"enabled"</code></td><td>The effect from this zone is enabled, overriding the effect from any enclosing 
+ *       zone.</td></tr>
+ *   </tbody>
+ * </table>
+ * @typedef {string} Entities.ComponentMode
+ */
 const char* componentModeNames[] = {
     "inherit",
     "disabled",
@@ -22,6 +38,20 @@ QString ComponentModeHelpers::getNameForComponentMode(ComponentMode mode) {
     return componentModeNames[(int)mode];
 }
 
+/**jsdoc
+ * <p>The priority of updates from avatars in a zone to other clients.</p>
+ * <table>
+ *   <thead>
+ *     <tr><th>Value</th><th>Description</th></tr>
+ *   </thead>
+ *   <tbody>
+ *     <tr><td><code>"inherit"</code></td><td>The update priority from any enclosing zone continues into this zone.</td></tr>
+ *     <tr><td><code>"crowd"</code></td><td>The update priority in this zone is the normal priority.</td></tr>
+ *     <tr><td><code>"hero"</code></td><td>Avatars in this zone have an increased update priority.</td></tr>
+ *   </tbody>
+ * </table>
+ * @typedef {string} Entities.AvatarPriorityMode
+ */
 const char* avatarPriorityModeNames[] = {
     "inherit",
     "crowd",

libraries/shared/src/GizmoType.h

@@ -12,16 +12,16 @@
 #include "QString"
 
 /**jsdoc
- * <p>Controls how the Gizmo behaves and renders</p>
+ * <p>A {@link Entities.EntityProperties-Gizmo|Gizmo} entity may be one of the following types:</p>
  * <table>
  *   <thead>
  *     <tr><th>Value</th><th>Description</th></tr>
  *   </thead>
  *   <tbody>
- *     <tr><td><code>ring</code></td><td>A ring gizmo.</td></tr>
+ *     <tr><td><code>"ring"</code></td><td>A ring gizmo.</td></tr>
  *   </tbody>
  * </table>
- * @typedef {string} GizmoType
+ * @typedef {string} Entities.GizmoType
  */
 
 enum GizmoType {

libraries/shared/src/PointerEvent.cpp

@@ -66,7 +66,7 @@ void PointerEvent::setButton(Button button) {
 }
 
 /**jsdoc
- * A PointerEvent defines a 2D or 3D mouse or similar pointer event.
+ * A 2D or 3D mouse or similar pointer event.
  * @typedef {object} PointerEvent
  * @property {string} type - The type of event: <code>"Press"</code>, <code>"DoublePress"</code>, <code>"Release"</code>, or
  *     <code>"Move"</code>.

libraries/shared/src/PrimitiveMode.h

@@ -12,17 +12,17 @@
 #include "QString"
 
 /**jsdoc
- * <p>How the geometry of the entity is rendered.</p>
+ * <p>How the geometry of an entity is rendered.</p>
  * <table>
  *   <thead>
  *     <tr><th>Value</th><th>Description</th></tr>
  *   </thead>
  *   <tbody>
- *     <tr><td><code>solid</code></td><td>The entity will be drawn as a solid shape.</td></tr>
+ *     <tr><td><code>"solid"</code></td><td>The entity is drawn as a solid shape.</td></tr>
- *     <tr><td><code>lines</code></td><td>The entity will be drawn as wireframe.</td></tr>
+ *     <tr><td><code>"lines"</code></td><td>The entity is drawn as wireframe.</td></tr>
  *   </tbody>
  * </table>
- * @typedef {string} PrimitiveMode
+ * @typedef {string} Entities.PrimitiveMode
  */
 
 enum class PrimitiveMode {

libraries/shared/src/PulseMode.h

@@ -18,12 +18,12 @@
  *     <tr><th>Value</th><th>Description</th></tr>
  *   </thead>
  *   <tbody>
- *     <tr><td><code>none</code></td><td>No pulsing.</td></tr>
+ *     <tr><td><code>"none"</code></td><td>No pulsing.</td></tr>
- *     <tr><td><code>in</code></td><td>Pulse in phase with the pulse period.</td></tr>
+ *     <tr><td><code>"in"</code></td><td>Pulse in phase with the pulse period.</td></tr>
- *     <tr><td><code>out</code></td><td>Pulse out of phase with the pulse period.</td></tr>
+ *     <tr><td><code>"out"</code></td><td>Pulse out of phase with the pulse period.</td></tr>
  *   </tbody>
  * </table>
- * @typedef {string} PulseMode
+ * @typedef {string} Entities.PulseMode
  */
 
 enum class PulseMode {

libraries/shared/src/RegisteredMetaTypes.h

@@ -122,43 +122,43 @@ glm::vec3 vec3FromVariant(const QVariant &object, bool& valid);
 glm::vec3 vec3FromVariant(const QVariant &object);
 
 /**jsdoc
-* A color vector. See also the {@link Vec3(0)|Vec3} object.
+ * A color vector. See also the {@link Vec3(0)|Vec3} object.
-*
+ *
-* @typedef {object} Color
+ * @typedef {object} Color
-* @property {number} red - Red component value. Integer in the range <code>0</code> - <code>255</code>.  Synonyms: <code>r</code>, <code>x</code>.
+ * @property {number} red - Red component value. Integer in the range <code>0</code> - <code>255</code>.  Synonyms: <code>r</code>, <code>x</code>.
-* @property {number} green - Green component value. Integer in the range <code>0</code> - <code>255</code>.  Synonyms: <code>g</code>, <code>y</code>.
+ * @property {number} green - Green component value. Integer in the range <code>0</code> - <code>255</code>.  Synonyms: <code>g</code>, <code>y</code>.
-* @property {number} blue - Blue component value. Integer in the range <code>0</code> - <code>255</code>.  Synonyms: <code>b</code>, <code>z</code>.
+ * @property {number} blue - Blue component value. Integer in the range <code>0</code> - <code>255</code>.  Synonyms: <code>b</code>, <code>z</code>.
-* @example <caption>Colors can be set in multiple ways and modified with their aliases, but still stringify in the same way</caption>
+ * @example <caption>Colors can be set in multiple ways and modified with their aliases, but still stringify in the same way</caption>
-* Entities.editEntity(<id>, { color: { x: 1, y: 2, z: 3 }});                 // { red: 1, green: 2, blue: 3 }
+ * Entities.editEntity(<id>, { color: { x: 1, y: 2, z: 3 }});                 // { red: 1, green: 2, blue: 3 }
-* Entities.editEntity(<id>, { color: { r: 4, g: 5, b: 6 }});                 // { red: 4, green: 5, blue: 6 }
+ * Entities.editEntity(<id>, { color: { r: 4, g: 5, b: 6 }});                 // { red: 4, green: 5, blue: 6 }
-* Entities.editEntity(<id>, { color: { red: 7, green: 8, blue: 9 }});        // { red: 7, green: 8, blue: 9 }
+ * Entities.editEntity(<id>, { color: { red: 7, green: 8, blue: 9 }});        // { red: 7, green: 8, blue: 9 }
-* Entities.editEntity(<id>, { color: [10, 11, 12] });                        // { red: 10, green: 11, blue: 12 }
+ * Entities.editEntity(<id>, { color: [10, 11, 12] });                        // { red: 10, green: 11, blue: 12 }
-* Entities.editEntity(<id>, { color: 13 });                                  // { red: 13, green: 13, blue: 13 }
+ * Entities.editEntity(<id>, { color: 13 });                                  // { red: 13, green: 13, blue: 13 }
-* var color = Entities.getEntityProperties(<id>).color;                      // { red: 13, green: 13, blue: 13 }
+ * var color = Entities.getEntityProperties(<id>).color;                      // { red: 13, green: 13, blue: 13 }
-* color.g = 14;                                                              // { red: 13, green: 14, blue: 13 }
+ * color.g = 14;                                                              // { red: 13, green: 14, blue: 13 }
-* color.blue = 15;                                                           // { red: 13, green: 14, blue: 15 }
+ * color.blue = 15;                                                           // { red: 13, green: 14, blue: 15 }
-* Entities.editEntity(<id>, { color: "red"});                                // { red: 255, green: 0, blue: 0 }
+ * Entities.editEntity(<id>, { color: "red"});                                // { red: 255, green: 0, blue: 0 }
-* Entities.editEntity(<id>, { color: "#00FF00"});                            // { red: 0, green: 255, blue: 0 }
+ * Entities.editEntity(<id>, { color: "#00FF00"});                            // { red: 0, green: 255, blue: 0 }
-*/
+ */
 /**jsdoc
-* A color vector. See also the {@link Vec3(0)|Vec3} object.
+ * A color vector with real values. Values may also be <code>null</code>. See also the {@link Vec3(0)|Vec3} object.
-*
+ *
-* @typedef {object} ColorFloat
+ * @typedef {object} ColorFloat
-* @property {number} red - Red component value. Real in the range <code>0</code> - <code>255</code>.  Synonyms: <code>r</code>, <code>x</code>.
+ * @property {number} red - Red component value. Real in the range <code>0</code> - <code>255</code>.  Synonyms: <code>r</code>, <code>x</code>.
-* @property {number} green - Green component value. Real in the range <code>0</code> - <code>255</code>.  Synonyms: <code>g</code>, <code>y</code>.
+ * @property {number} green - Green component value. Real in the range <code>0</code> - <code>255</code>.  Synonyms: <code>g</code>, <code>y</code>.
-* @property {number} blue - Blue component value. Real in the range <code>0</code> - <code>255</code>.  Synonyms: <code>b</code>, <code>z</code>.
+ * @property {number} blue - Blue component value. Real in the range <code>0</code> - <code>255</code>.  Synonyms: <code>b</code>, <code>z</code>.
-* @example <caption>ColorFloats can be set in multiple ways and modified with their aliases, but still stringify in the same way</caption>
+ * @example <caption>ColorFloats can be set in multiple ways and modified with their aliases, but still stringify in the same way</caption>
-* Entities.editEntity(<id>, { color: { x: 1, y: 2, z: 3 }});                 // { red: 1, green: 2, blue: 3 }
+ * Entities.editEntity(<id>, { color: { x: 1, y: 2, z: 3 }});                 // { red: 1, green: 2, blue: 3 }
-* Entities.editEntity(<id>, { color: { r: 4, g: 5, b: 6 }});                 // { red: 4, green: 5, blue: 6 }
+ * Entities.editEntity(<id>, { color: { r: 4, g: 5, b: 6 }});                 // { red: 4, green: 5, blue: 6 }
-* Entities.editEntity(<id>, { color: { red: 7, green: 8, blue: 9 }});        // { red: 7, green: 8, blue: 9 }
+ * Entities.editEntity(<id>, { color: { red: 7, green: 8, blue: 9 }});        // { red: 7, green: 8, blue: 9 }
-* Entities.editEntity(<id>, { color: [10, 11, 12] });                        // { red: 10, green: 11, blue: 12 }
+ * Entities.editEntity(<id>, { color: [10, 11, 12] });                        // { red: 10, green: 11, blue: 12 }
-* Entities.editEntity(<id>, { color: 13 });                                  // { red: 13, green: 13, blue: 13 }
+ * Entities.editEntity(<id>, { color: 13 });                                  // { red: 13, green: 13, blue: 13 }
-* var color = Entities.getEntityProperties(<id>).color;                      // { red: 13, green: 13, blue: 13 }
+ * var color = Entities.getEntityProperties(<id>).color;                      // { red: 13, green: 13, blue: 13 }
-* color.g = 14;                                                              // { red: 13, green: 14, blue: 13 }
+ * color.g = 14;                                                              // { red: 13, green: 14, blue: 13 }
-* color.blue = 15;                                                           // { red: 13, green: 14, blue: 15 }
+ * color.blue = 15;                                                           // { red: 13, green: 14, blue: 15 }
-* Entities.editEntity(<id>, { color: "red"});                                // { red: 255, green: 0, blue: 0 }
+ * Entities.editEntity(<id>, { color: "red"});                                // { red: 255, green: 0, blue: 0 }
-* Entities.editEntity(<id>, { color: "#00FF00"});                            // { red: 0, green: 255, blue: 0 }
+ * Entities.editEntity(<id>, { color: "#00FF00"});                            // { red: 0, green: 255, blue: 0 }
-*/
+ */
 QScriptValue u8vec3ToScriptValue(QScriptEngine* engine, const glm::u8vec3& vec3);
 QScriptValue u8vec3ColorToScriptValue(QScriptEngine* engine, const glm::u8vec3& vec3);
 void u8vec3FromScriptValue(const QScriptValue& object, glm::u8vec3& vec3);

libraries/shared/src/RenderLayer.h

@@ -12,18 +12,18 @@
 #include "QString"
 
 /**jsdoc
- * <p>In which layer an entity is rendered.</p>
+ * <p>A layer in which an entity may be rendered.</p>
  * <table>
  *   <thead>
  *     <tr><th>Value</th><th>Description</th></tr>
  *   </thead>
  *   <tbody>
- *     <tr><td><code>world</code></td><td>The entity will be drawn in the world with everything else.</td></tr>
+ *     <tr><td><code>"world"</code></td><td>The entity is drawn in the world with everything else.</td></tr>
- *     <tr><td><code>front</code></td><td>The entity will be drawn on top of the world layer, but behind the HUD sphere.</td></tr>
+ *     <tr><td><code>"front"</code></td><td>The entity is drawn on top of the world layer but behind the HUD sphere.</td></tr>
- *     <tr><td><code>hud</code></td><td>The entity will be drawn on top of other layers and the HUD sphere.</td></tr>
+ *     <tr><td><code>"hud"</code></td><td>The entity is drawn on top of other layers and the HUD sphere.</td></tr>
  *   </tbody>
  * </table>
- * @typedef {string} RenderLayer
+ * @typedef {string} Entities.RenderLayer
  */
 
 enum class RenderLayer {

libraries/shared/src/ShapeInfo.cpp

@@ -17,7 +17,7 @@
 #include "NumericalConstants.h" // for MILLIMETERS_PER_METER
 
 /**jsdoc
- * <p>A ShapeType defines the shape used for collisions or zones.</p>
+ * <p>Defines the shape used for collisions or zones.</p>
  * <table>
  *   <thead>
  *     <tr><th>Value</th><th>Description</th></tr>

libraries/shared/src/SpatiallyNestable.cpp

@@ -1348,7 +1348,20 @@ SpatiallyNestablePointer SpatiallyNestable::findByID(QUuid id, bool& success) {
     return parentWP.lock();
 }
 
-
+/**jsdoc
+ * <p>An in-world item may be one of the following types:</p>
+ * <table>
+ *   <thead>
+ *     <tr><th>Value</th><th>Description</th></tr>
+ *   </thead>
+ *   <tbody>
+ *     <tr><td><code>"entity"</code></td><td>The item is an entity.</td></tr>
+ *     <tr><td><code>"avatar"</code></td><td>The item is an avatar.</td></tr>
+ *     <tr><td><code>"unknown"</code></td><td>The item cannot be found.</td></tr>
+ *   </tbody>
+ * </table>
+ * @typedef {string} Entities.NestableType
+ */
 QString SpatiallyNestable::nestableTypeToString(NestableType nestableType) {
     switch(nestableType) {
         case NestableType::Entity:

libraries/shared/src/WebInputMode.h

@@ -12,14 +12,14 @@
 #include "QString"
 
 /**jsdoc
- * <p>Controls how the web surface processed PointerEvents</p>
+ * <p>Specifies how a web surface processes events.</p>
  * <table>
  *   <thead>
  *     <tr><th>Value</th><th>Description</th></tr>
  *   </thead>
  *   <tbody>
- *     <tr><td><code>touch</code></td><td>Events are processed as touch events.</td></tr>
+ *     <tr><td><code>"touch"</code></td><td>Events are processed as touch events.</td></tr>
- *     <tr><td><code>mouse</code></td><td>Events are processed as mouse events.</td></tr>
+ *     <tr><td><code>"mouse"</code></td><td>Events are processed as mouse events.</td></tr>
  *   </tbody>
  * </table>
  * @typedef {string} WebInputMode