Merge pull request #16492 from jennaingersoll/jsdoc-revisions

DOC-208: Revisions to JSDoc added by developers since July 2019
This commit is contained in:
jennaingersoll 2019-11-19 11:01:18 -08:00 committed by GitHub
commit 451ffcd1e0
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
7 changed files with 109 additions and 60 deletions

View file

@ -76,6 +76,22 @@
* 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>
* @property {boolean} hasScriptedBlendshapes=false - <code>true</code> if blend shapes are controlled by scripted actions,
* otherwise <code>false</code>. Set this to <code>true</code> before using the {@link MyAvatar.setBlendshape} method,
* and set back to <code>false</code> after you no longer want scripted control over the blend shapes.
* <p><strong>Note:</strong> This property will automatically be set to true if the Controller system has valid facial
* blend shape actions.</p>
* @property {boolean} hasProceduralBlinkFaceMovement=true - <code>true</code> if avatars blink automatically by animating
* facial blend shapes, <code>false</code> if automatic blinking is disabled. Set this property to <code>false</code> if
* you wish to fully control the blink facial blend shapes via the {@link MyAvatar.setBlendshape} method.
* @property {boolean} hasProceduralEyeFaceMovement=true - <code>true</code> if the facial blend shapes for an avatar's eyes
* adjust automatically as the eyes move, <code>false</code> if this automatic movement is disabled. Set this property
* to <code>true</code> to prevent the iris from being obscured by the upper or lower lids. Set this property to
* <code>false</code> if you wish to fully control the eye blend shapes via the {@link MyAvatar.setBlendshape} method.
* @property {boolean} hasAudioEnabledFaceMovement=true - <code>true</code> if the avatar's mouth blend shapes animate
* automatically based on detected microphone input, <code>false</code> if this automatic movement is disabled. Set
* this property to <code>false</code> if you wish to fully control the mouth facial blend shapes via the
* {@link MyAvatar.setBlendshape} method.
*
* @example <caption>Create a scriptable avatar.</caption>
* (function () {

View file

@ -148,6 +148,22 @@ class MyAvatar : public Avatar {
* 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>
* @property {boolean} hasScriptedBlendshapes=false - <code>true</code> if blend shapes are controlled by scripted actions,
* otherwise <code>false</code>. Set this to <code>true</code> before using the {@link MyAvatar.setBlendshape} method,
* and set back to <code>false</code> after you no longer want scripted control over the blend shapes.
* <p><strong>Note:</strong> This property will automatically be set to true if the Controller system has valid facial
* blend shape actions.</p>
* @property {boolean} hasProceduralBlinkFaceMovement=true - <code>true</code> if avatars blink automatically by animating
* facial blend shapes, <code>false</code> if automatic blinking is disabled. Set this property to <code>false</code> if
* you wish to fully control the blink facial blend shapes via the {@link MyAvatar.setBlendshape} method.
* @property {boolean} hasProceduralEyeFaceMovement=true - <code>true</code> if the facial blend shapes for an avatar's eyes
* adjust automatically as the eyes move, <code>false</code> if this automatic movement is disabled. Set this property
* to <code>true</code> to prevent the iris from being obscured by the upper or lower lids. Set this property to
* <code>false</code> if you wish to fully control the eye blend shapes via the {@link MyAvatar.setBlendshape} method.
* @property {boolean} hasAudioEnabledFaceMovement=true - <code>true</code> if the avatar's mouth blend shapes animate
* automatically based on detected microphone input, <code>false</code> if this automatic movement is disabled. Set
* this property to <code>false</code> if you wish to fully control the mouth facial blend shapes via the
* {@link MyAvatar.setBlendshape} method.
*
* @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
@ -1746,7 +1762,7 @@ public:
void prepareAvatarEntityDataForReload();
/**jsdoc
* Turn the avatar's head until it faces the target point within the 90/-90 degree range.
* Turns the avatar's head until it faces the target point within a +90/-90 degree range.
* Once this method is called, API calls will have full control of the head for a limited time.
* If this method is not called for two seconds, the engine will regain control of the head.
* @function MyAvatar.setHeadLookAt
@ -1755,47 +1771,46 @@ public:
Q_INVOKABLE void setHeadLookAt(const glm::vec3& lookAtTarget);
/**jsdoc
* Returns the current head look at target point in world coordinates.
* Returns the current target point of the head's look direction in world coordinates.
* @function MyAvatar.getHeadLookAt
* @returns {Vec3} The head's look at target in world coordinates.
* @returns {Vec3} The head's "look at" target in world coordinates.
*/
Q_INVOKABLE glm::vec3 getHeadLookAt() { return _lookAtCameraTarget; }
/**jsdoc
* When this function is called the engine regains control of the head immediately.
* Returns control of the avatar's head to the engine, and releases control from API calls.
* @function MyAvatar.releaseHeadLookAtControl
*/
Q_INVOKABLE void releaseHeadLookAtControl();
/**jsdoc
* Force the avatar's eyes to look to the specified location.
* Once this method is called, API calls will have full control of the eyes for a limited time.
* If this method is not called for two seconds, the engine will regain control of the eyes.
* Forces the avatar's eyes to look at a specified location. Once this method is called, API calls
* have full control of the eyes for a limited time. If this method is not called for two seconds,
* the engine regains control of the eyes.
* @function MyAvatar.setEyesLookAt
* @param {Vec3} lookAtTarget - The target point in world coordinates.
*/
Q_INVOKABLE void setEyesLookAt(const glm::vec3& lookAtTarget);
/**jsdoc
* Returns the current eyes look at target point in world coordinates.
* Returns the current target point of the eyes look direction in world coordinates.
* @function MyAvatar.getEyesLookAt
* @returns {Vec3} The eyes's look at target in world coordinates.
* @returns {Vec3} The eyes' "look at" target in world coordinates.
*/
Q_INVOKABLE glm::vec3 getEyesLookAt() { return _eyesLookAtTarget.get(); }
/**jsdoc
* When this function is called the engine regains control of the eyes immediately.
* Returns control of the avatar's eyes to the engine, and releases control from API calls.
* @function MyAvatar.releaseEyesLookAtControl
*/
Q_INVOKABLE void releaseEyesLookAtControl();
/**jsdoc
* Aims the pointing directional blending towards the provided target point.
* The "point" reaction should be triggered before using this method.
* <code>MyAvatar.beginReaction("point")</code>
* Returns <code>true</code> if the target point lays in front of the avatar.
* Aims the pointing directional blending towards the provided target point. The "point" reaction should be triggered
* before using this method with the code <code>MyAvatar.beginReaction("point")</code>.
* @function MyAvatar.setPointAt
* @param {Vec3} pointAtTarget - The target point in world coordinates.
* @returns {boolean} <code>true</code> if the target point lays in front of the avatar, <code>false</code> if it doesn't.
*/
Q_INVOKABLE bool setPointAt(const glm::vec3& pointAtTarget);
@ -1899,7 +1914,7 @@ public:
Q_INVOKABLE QVariantList getCollidingFlowJoints();
/**jsdoc
* Starts a sitting action for the avatar
* Starts a sitting action for the avatar.
* @function MyAvatar.beginSit
* @param {Vec3} position - The point in space where the avatar will sit.
* @param {Quat} rotation - Initial absolute orientation of the avatar once is seated.
@ -1907,7 +1922,7 @@ public:
Q_INVOKABLE void beginSit(const glm::vec3& position, const glm::quat& rotation);
/**jsdoc
* Ends a sitting action for the avatar
* Ends a sitting action for the avatar.
* @function MyAvatar.endSit
* @param {Vec3} position - The position of the avatar when standing up.
* @param {Quat} rotation - The absolute rotation of the avatar once the sitting action ends.

View file

@ -99,9 +99,11 @@ PickFilter getPickFilter(unsigned int filter) {
* @property {Vec3} [dirOffset] - Synonym for <code>direction</code>.
* @property {Quat} [orientation] - Alternative property for specifying <code>direction</code>. The value is applied to the
* default <code>direction</code> value.
* @property {PickType} pickType - The type of pick when getting these properties from {@link Picks.getPickProperties} or {@link Picks.getPickScriptParameters}. A ray pick's type is {@link PickType.Ray}.
* @property {Vec3} baseScale - Returned from {@link Picks.getPickProperties} when the pick has a parent with varying scale (usually an avatar or an entity).
* Its value is the original scale of the parent at the moment the pick was created, and is used to scale the pointer which owns this pick, if any.
* @property {PickType} pickType - The type of pick when getting these properties from {@link Picks.getPickProperties} or
* {@link Picks.getPickScriptParameters}. A ray pick's type is {@link PickType.Ray}.
* @property {Vec3} baseScale - Returned from {@link Picks.getPickProperties} when the pick has a parent with varying scale
* (usually an avatar or an entity). Its value is the original scale of the parent at the moment the pick was created, and
* is used to scale the pointer which owns this pick, if any.
*/
std::shared_ptr<PickQuery> PickScriptingInterface::buildRayPick(const QVariantMap& propMap) {
#if defined (Q_OS_ANDROID)
@ -170,7 +172,8 @@ std::shared_ptr<PickQuery> PickScriptingInterface::buildRayPick(const QVariantMa
* means no maximum.
* @property {Vec3} [tipOffset=0,0.095,0] - The position of the stylus tip relative to the hand position at default avatar
* scale.
* @property {PickType} pickType - The type of pick when getting these properties from {@link Picks.getPickProperties} or {@link Picks.getPickScriptParameters}. A stylus pick's type is {@link PickType.Stylus}.
* @property {PickType} pickType - The type of pick when getting these properties from {@link Picks.getPickProperties} or
* {@link Picks.getPickScriptParameters}. A stylus pick's type is {@link PickType.Stylus}.
*/
std::shared_ptr<PickQuery> PickScriptingInterface::buildStylusPick(const QVariantMap& propMap) {
bilateral::Side side = bilateral::Side::Invalid;
@ -204,7 +207,8 @@ std::shared_ptr<PickQuery> PickScriptingInterface::buildStylusPick(const QVarian
return std::make_shared<StylusPick>(side, filter, maxDistance, enabled, tipOffset);
}
// NOTE: Laser pointer still uses scaleWithAvatar. Until scaleWithAvatar is also deprecated for pointers, scaleWithAvatar should not be removed from the pick API.
// NOTE: Laser pointer still uses scaleWithAvatar. Until scaleWithAvatar is also deprecated for pointers, scaleWithAvatar
// should not be removed from the pick API.
/**jsdoc
* The properties of a parabola pick.
*
@ -245,9 +249,11 @@ std::shared_ptr<PickQuery> PickScriptingInterface::buildStylusPick(const QVarian
* with the avatar or other parent.
* @property {boolean} [scaleWithAvatar=true] - Synonym for <code>scalewithParent</code>.
* <p class="important">Deprecated: This property is deprecated and will be removed.</p>
* @property {PickType} pickType - The type of pick when getting these properties from {@link Picks.getPickProperties} or {@link Picks.getPickScriptParameters}. A parabola pick's type is {@link PickType.Parabola}.
* @property {Vec3} baseScale - Returned from {@link Picks.getPickProperties} when the pick has a parent with varying scale (usually an avatar or an entity).
* Its value is the original scale of the parent at the moment the pick was created, and is used to rescale the pick, and/or the pointer which owns this pick, if any.
* @property {PickType} pickType - The type of pick when getting these properties from {@link Picks.getPickProperties} or
* {@link Picks.getPickScriptParameters}. A parabola pick's type is {@link PickType.Parabola}.
* @property {Vec3} baseScale - Returned from {@link Picks.getPickProperties} when the pick has a parent with varying scale
* (usually an avatar or an entity). Its value is the original scale of the parent at the moment the pick was created, and
* is used to rescale the pick and the pointer which owns this pick, if any.
*/
std::shared_ptr<PickQuery> PickScriptingInterface::buildParabolaPick(const QVariantMap& propMap) {
bool enabled = false;

View file

@ -152,19 +152,20 @@ public:
* Gets the current properties of the pick.
* @function Picks.getPickProperties
* @param {number} id - The ID of the pick.
* @returns {Picks.RayPickProperties|Picks.ParabolaPickProperties|Picks.StylusPickProperties|Picks.CollisionPickProperties} Properties of the pick, per the pick <code>type</code>.
* @returns {Picks.RayPickProperties|Picks.ParabolaPickProperties|Picks.StylusPickProperties|Picks.CollisionPickProperties}
* Properties of the pick, per the pick <code>type</code>.
*/
Q_INVOKABLE QVariantMap getPickProperties(unsigned int uid) const;
/**jsdoc
* Gets the parameters that were passed in to {@link Picks.createPick} to create the pick,
* if the pick was created through a script.
* Note that these properties do not reflect the current state of the pick.
* See {@link Picks.getPickProperties}.
* @function Picks.getPickScriptParameters
* @param {number} id - The ID of the pick.
* @returns {Picks.RayPickProperties|Picks.ParabolaPickProperties|Picks.StylusPickProperties|Picks.CollisionPickProperties} User-provided properties, per the pick <code>type</code>.
*/
* Gets the parameters that were passed in to {@link Picks.createPick} to create the pick, if the pick was created through
* a script. Note that these properties do not reflect the current state of the pick.
* See {@link Picks.getPickProperties}.
* @function Picks.getPickScriptParameters
* @param {number} id - The ID of the pick.
* @returns {Picks.RayPickProperties|Picks.ParabolaPickProperties|Picks.StylusPickProperties|Picks.CollisionPickProperties}
* Script-provided properties, per the pick <code>type</code>.
*/
Q_INVOKABLE QVariantMap getPickScriptParameters(unsigned int uid) const;
/**jsdoc

View file

@ -89,10 +89,13 @@ QVariantMap PointerScriptingInterface::getPointerScriptParameters(unsigned int u
* @property {Pointers.StylusPointerModel} [model] - Override some or all of the default stylus model properties.
* @property {boolean} [hover=false] - <code>true</code> if the pointer generates {@link Entities} hover events,
* <code>false</code> if it doesn't.
* @property {PickType} pointerType - The type of pointer when getting these properties from {@link Pointers.getPointerProperties} or {@link Pointers.getPointerScriptParameters}. A stylus pointer's type is {@link PickType.Stylus}.
* @property {number} [pickID] - Returned from {@link Pointers.getPointerProperties}. The ID of the pick created alongside this pointer.
* @property {PickType} pointerType - The type of the stylus pointer returned from {@link Pointers.getPointerProperties}
* or {@link Pointers.getPointerScriptParameters}. A stylus pointer's type is {@link PickType(0)|PickType.Stylus}.
* @property {number} [pickID] - The ID of the pick created alongside this pointer, returned from
* {@link Pointers.getPointerProperties}.
* @see {@link Picks.StylusPickProperties} for additional properties from the underlying stylus pick.
*/
/**jsdoc
* The properties of a stylus pointer model.
* @typedef {object} Pointers.StylusPointerModel
@ -208,8 +211,10 @@ std::shared_ptr<Pointer> PointerScriptingInterface::buildStylus(const QVariant&
* <code>false</code> if it doesn't.
* @property {Pointers.Trigger[]} [triggers=[]] - A list of ways that a {@link Controller} action or function should trigger
* events on the entity or overlay currently intersected.
* @property {PickType} pointerType - The type of pointer when getting these properties from {@link Pointers.getPointerProperties} or {@link Pointers.getPointerScriptParameters}. A laser pointer's type is {@link PickType.Ray}.
* @property {number} [pickID] - Returned from {@link Pointers.getPointerProperties}. The ID of the pick created alongside this pointer.
* @property {PickType} pointerType - The type of pointer returned from {@link Pointers.getPointerProperties} or
* {@link Pointers.getPointerScriptParameters}. A laser pointer's type is {@link PickType(0)|PickType.Ray}.
* @property {number} [pickID] - The ID of the pick created alongside this pointer, returned from
* {@link Pointers.getPointerProperties}.
* @see {@link Picks.RayPickProperties} for additional properties from the underlying ray pick.
*/
std::shared_ptr<Pointer> PointerScriptingInterface::buildLaserPointer(const QVariant& properties) {
@ -401,8 +406,10 @@ std::shared_ptr<Pointer> PointerScriptingInterface::buildLaserPointer(const QVar
* <code>false</code> if it doesn't.
* @property {Pointers.Trigger[]} [triggers=[]] - A list of ways that a {@link Controller} action or function should trigger
* events on the entity or overlay currently intersected.
* @property {PickType} pointerType - The type of pointer when getting these properties from {@link Pointers.getPointerProperties} or {@link Pointers.getPointerScriptParameters}. A parabola pointer's type is {@link PickType.Parabola}.
* @property {number} [pickID] - Returned from {@link Pointers.getPointerProperties}. The ID of the pick created alongside this pointer.
* @property {PickType} pointerType - The type of pointer returned from {@link Pointers.getPointerProperties} or
* {@link Pointers.getPointerScriptParameters}. A parabola pointer's type is {@link PickType(0)|PickType.Parabola}.
* @property {number} [pickID] - The ID of the pick created alongside this pointer, returned from
* {@link Pointers.getPointerProperties}.
* @see {@link Picks.ParabolaPickProperties} for additional properties from the underlying parabola pick.
*/
std::shared_ptr<Pointer> PointerScriptingInterface::buildParabolaPointer(const QVariant& properties) {

View file

@ -161,13 +161,14 @@ public:
Q_INVOKABLE void removePointer(unsigned int uid) const { DependencyManager::get<PointerManager>()->removePointer(uid); }
/**jsdoc
* Gets the parameters that were passed in to {@link Pointers.createPointer} to create the pointer,
* if the pointer was created through a script.
* Note that these properties do not reflect the current state of the pointer.
* See {@link Pointers.getPointerProperties}.
* Gets the parameters that were passed in to {@link Pointers.createPointer} to create the pointer when the pointer was
* created through a script.
* <p><strong>Note:</strong> These properties do not reflect the current state of the pointer. To get the current state
* of the pointer, see {@link Pointers.getPointerProperties}.
* @function Pointers.getPointerScriptParameters
* @param {number} id - The ID of the pointer.
* @returns {Pointers.RayPointerProperties|Picks.ParabolaPointerProperties|Picks.StylusPointerProperties} User-provided properties, per the pointer <code>type</code>.
* @returns {Pointers.RayPointerProperties|Picks.ParabolaPointerProperties|Picks.StylusPointerProperties}
* Script-provided properties, per the pointer <code>type</code>.
*/
Q_INVOKABLE QVariantMap getPointerScriptParameters(unsigned int uid) const;

View file

@ -532,19 +532,22 @@ class AvatarData : public QObject, public SpatiallyNestable {
* 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>
* @property {boolean} hasScriptedBlendshapes=false - Set this to true before using the {@link MyAvatar.setBlendshape} method,
* after you no longer want scripted control over the blendshapes set to back to false.<br /> NOTE: this property will
* automatically become true if the Controller system has valid facial blendshape actions.
* @property {boolean} hasProceduralBlinkFaceMovement=true - By default avatars will blink automatically by animating facial
* blendshapes. Set this property to <code>false</code> to disable this automatic blinking. This can be useful if you
* wish to fully control the blink facial blendshapes via the {@link MyAvatar.setBlendshape} method.
* @property {boolean} hasProceduralEyeFaceMovement=true - By default the avatar eye facial blendshapes will be adjusted
* automatically as the eyes move. This will prevent the iris is never obscured by the upper or lower lids. Set this
* property to <code>false</code> to disable this automatic movement. This can be useful if you wish to fully control
* the eye blendshapes via the {@link MyAvatar.setBlendshape} method.
* @property {boolean} hasAudioEnabledFaceMovement=true - By default the avatar mouth blendshapes will animate based on
* the microphone audio. Set this property to <code>false</code> to disable that animaiton. This can be useful if you
* wish to fully control the blink facial blendshapes via the {@link MyAvatar.setBlendshape} method.
* @property {boolean} hasScriptedBlendshapes=false - <code>true</code> if blend shapes are controlled by scripted actions,
* otherwise <code>false</code>. Set this to <code>true</code> before using the {@link MyAvatar.setBlendshape} method,
* and set back to <code>false</code> after you no longer want scripted control over the blend shapes.
* <p><strong>Note:</strong> This property will automatically be set to true if the Controller system has valid facial
* blend shape actions.</p>
* @property {boolean} hasProceduralBlinkFaceMovement=true - <code>true</code> if avatars blink automatically by animating
* facial blend shapes, <code>false</code> if automatic blinking is disabled. Set this property to <code>false</code> if
* you wish to fully control the blink facial blend shapes via the {@link MyAvatar.setBlendshape} method.
* @property {boolean} hasProceduralEyeFaceMovement=true - <code>true</code> if the facial blend shapes for an avatar's eyes
* adjust automatically as the eyes move, <code>false</code> if this automatic movement is disabled. Set this property
* to <code>true</code> to prevent the iris from being obscured by the upper or lower lids. Set this property to
* <code>false</code> if you wish to fully control the eye blend shapes via the {@link MyAvatar.setBlendshape} method.
* @property {boolean} hasAudioEnabledFaceMovement=true - <code>true</code> if the avatar's mouth blend shapes animate
* automatically based on detected microphone input, <code>false</code> if this automatic movement is disabled. Set
* this property to <code>false</code> if you wish to fully control the mouth facial blend shapes via the
* {@link MyAvatar.setBlendshape} method.
*/
Q_PROPERTY(glm::vec3 position READ getWorldPosition WRITE setPositionViaScript)
Q_PROPERTY(float scale READ getDomainLimitedScale WRITE setTargetScale)
@ -1130,9 +1133,9 @@ public:
/**jsdoc
* Sets the value of a blendshape to animate your avatar's face. To enable other users to see the resulting animation of
* your avatar's face, set {@link Avatar.hasScriptedBlendshapes} to true while using this API and back to false when your
* animation is complete.
* Sets the value of a blend shape to animate your avatar's face. In order for other users to see the resulting animations
* on your avatar's face, set {@link Avatar.hasScriptedBlendshapes} to <code>true</code>. When you are done using this API,
* set {@link Avatar.hasScriptedBlendshapes} back to <code>false</code> when the animation is complete.
* @function Avatar.setBlendshape
* @param {string} name - The name of the blendshape, per the
* {@link https://docs.highfidelity.com/create/avatars/avatar-standards.html#blendshapes Avatar Standards}.