From a61857b6d8a1e74c06561114325d916c81e30b07 Mon Sep 17 00:00:00 2001 From: ingerjm0 Date: Tue, 12 Nov 2019 14:17:23 -0800 Subject: [PATCH] JSDoc revisions for PR16025 --- .../src/raypick/PickScriptingInterface.cpp | 22 ++++++++++++------- .../src/raypick/PickScriptingInterface.h | 19 ++++++++-------- .../src/raypick/PointerScriptingInterface.cpp | 19 +++++++++++----- .../src/raypick/PointerScriptingInterface.h | 11 +++++----- 4 files changed, 43 insertions(+), 28 deletions(-) diff --git a/interface/src/raypick/PickScriptingInterface.cpp b/interface/src/raypick/PickScriptingInterface.cpp index 3a7b67a8e9..035ffde374 100644 --- a/interface/src/raypick/PickScriptingInterface.cpp +++ b/interface/src/raypick/PickScriptingInterface.cpp @@ -99,9 +99,11 @@ PickFilter getPickFilter(unsigned int filter) { * @property {Vec3} [dirOffset] - Synonym for direction. * @property {Quat} [orientation] - Alternative property for specifying direction. The value is applied to the * default direction 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 PickScriptingInterface::buildRayPick(const QVariantMap& propMap) { #if defined (Q_OS_ANDROID) @@ -170,7 +172,8 @@ std::shared_ptr 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 PickScriptingInterface::buildStylusPick(const QVariantMap& propMap) { bilateral::Side side = bilateral::Side::Invalid; @@ -204,7 +207,8 @@ std::shared_ptr PickScriptingInterface::buildStylusPick(const QVarian return std::make_shared(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 PickScriptingInterface::buildStylusPick(const QVarian * with the avatar or other parent. * @property {boolean} [scaleWithAvatar=true] - Synonym for scalewithParent. *

Deprecated: This property is deprecated and will be removed.

- * @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/or the pointer which owns this pick, if any. */ std::shared_ptr PickScriptingInterface::buildParabolaPick(const QVariantMap& propMap) { bool enabled = false; diff --git a/interface/src/raypick/PickScriptingInterface.h b/interface/src/raypick/PickScriptingInterface.h index e26b91b9a2..b1943e5a39 100644 --- a/interface/src/raypick/PickScriptingInterface.h +++ b/interface/src/raypick/PickScriptingInterface.h @@ -147,19 +147,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 type. + * @returns {Picks.RayPickProperties|Picks.ParabolaPickProperties|Picks.StylusPickProperties|Picks.CollisionPickProperties} + * Properties of the pick, per the pick type. */ 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 type. - */ + * 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 type. + */ Q_INVOKABLE QVariantMap getPickScriptParameters(unsigned int uid) const; /**jsdoc diff --git a/interface/src/raypick/PointerScriptingInterface.cpp b/interface/src/raypick/PointerScriptingInterface.cpp index 3520aacbd0..e8069d12c7 100644 --- a/interface/src/raypick/PointerScriptingInterface.cpp +++ b/interface/src/raypick/PointerScriptingInterface.cpp @@ -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] - true if the pointer generates {@link Entities} hover events, * false 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.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 PointerScriptingInterface::buildStylus(const QVariant& * false 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.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 PointerScriptingInterface::buildLaserPointer(const QVariant& properties) { @@ -401,8 +406,10 @@ std::shared_ptr PointerScriptingInterface::buildLaserPointer(const QVar * false 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.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 PointerScriptingInterface::buildParabolaPointer(const QVariant& properties) { diff --git a/interface/src/raypick/PointerScriptingInterface.h b/interface/src/raypick/PointerScriptingInterface.h index 2d2f3f6dae..c4f0d832e3 100644 --- a/interface/src/raypick/PointerScriptingInterface.h +++ b/interface/src/raypick/PointerScriptingInterface.h @@ -161,13 +161,14 @@ public: Q_INVOKABLE void removePointer(unsigned int uid) const { DependencyManager::get()->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. + *

Note: 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 type. + * @returns {Pointers.RayPointerProperties|Picks.ParabolaPointerProperties|Picks.StylusPointerProperties} + * User-provided properties, per the pointer type. */ Q_INVOKABLE QVariantMap getPointerScriptParameters(unsigned int uid) const;