From 42cb3d9828623f8ced407b3f34b52b589930f455 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Thu, 6 Jun 2019 10:26:43 +1200 Subject: [PATCH] Polish Vec3 API JSDoc --- libraries/script-engine/src/Vec3.h | 71 +++++++++++----------- libraries/shared/src/RegisteredMetaTypes.h | 3 +- 2 files changed, 39 insertions(+), 35 deletions(-) diff --git a/libraries/script-engine/src/Vec3.h b/libraries/script-engine/src/Vec3.h index 7887938004..86df912d0e 100644 --- a/libraries/script-engine/src/Vec3.h +++ b/libraries/script-engine/src/Vec3.h @@ -22,8 +22,8 @@ #include "GLMHelpers.h" /**jsdoc - * The Vec3 API facilities for generating and manipulating 3-dimensional vectors. High Fidelity uses a right-handed - * Cartesian coordinate system where the y-axis is the "up" and the negative z-axis is the "front" direction. + * The Vec3 API provides facilities for generating and manipulating 3-dimensional vectors. High Fidelity uses a + * right-handed Cartesian coordinate system where the y-axis is the "up" and the negative z-axis is the "front" direction. * High Fidelity coordinate system * * @namespace Vec3 @@ -98,7 +98,7 @@ class Vec3 : public QObject, protected QScriptable { public slots: /**jsdoc - * Calculate the reflection of a vector in a plane. + * Calculates the reflection of a vector in a plane. * @function Vec3(0).reflect * @param {Vec3} v - The vector to reflect. * @param {Vec3} normal - The normal of the plane. @@ -112,7 +112,7 @@ public slots: glm::vec3 reflect(const glm::vec3& v1, const glm::vec3& v2) { return glm::reflect(v1, v2); } /**jsdoc - * Calculate the cross product of two vectors. + * Calculates the cross product of two vectors. * @function Vec3(0).cross * @param {Vec3} v1 - The first vector. * @param {Vec3} v2 - The second vector. @@ -126,7 +126,7 @@ public slots: glm::vec3 cross(const glm::vec3& v1, const glm::vec3& v2) { return glm::cross(v1, v2); } /**jsdoc - * Calculate the dot product of two vectors. + * Calculates the dot product of two vectors. * @function Vec3(0).dot * @param {Vec3} v1 - The first vector. * @param {Vec3} v2 - The second vector. @@ -140,7 +140,7 @@ public slots: float dot(const glm::vec3& v1, const glm::vec3& v2) { return glm::dot(v1, v2); } /**jsdoc - * Multiply a vector by a scale factor. + * Multiplies a vector by a scale factor. * @function Vec3(0).multiply * @param {Vec3} v - The vector. * @param {number} scale - The scale factor. @@ -149,7 +149,7 @@ public slots: glm::vec3 multiply(const glm::vec3& v1, float f) { return v1 * f; } /**jsdoc - * Multiply a vector by a scale factor. + * Multiplies a vector by a scale factor. * @function Vec3(0).multiply * @param {number} scale - The scale factor. * @param {Vec3} v - The vector. @@ -158,7 +158,7 @@ public slots: glm::vec3 multiply(float f, const glm::vec3& v1) { return v1 * f; } /**jsdoc - * Multiply two vectors. + * Multiplies two vectors. * @function Vec3(0).multiplyVbyV * @param {Vec3} v1 - The first vector. * @param {Vec3} v2 - The second vector. @@ -173,7 +173,7 @@ public slots: glm::vec3 multiplyVbyV(const glm::vec3& v1, const glm::vec3& v2) { return v1 * v2; } /**jsdoc - * Rotate a vector. + * Rotates a vector. * @function Vec3(0).multiplyQbyV * @param {Quat} q - The rotation to apply. * @param {Vec3} v - The vector to rotate. @@ -187,7 +187,7 @@ public slots: glm::vec3 multiplyQbyV(const glm::quat& q, const glm::vec3& v) { return q * v; } /**jsdoc - * Calculate the sum of two vectors. + * Calculates the sum of two vectors. * @function Vec3(0).sum * @param {Vec3} v1 - The first vector. * @param {Vec3} v2 - The second vector. @@ -196,7 +196,7 @@ public slots: glm::vec3 sum(const glm::vec3& v1, const glm::vec3& v2) { return v1 + v2; } /**jsdoc - * Calculate one vector subtracted from another. + * Calculates one vector subtracted from another. * @function Vec3(0).subtract * @param {Vec3} v1 - The first vector. * @param {Vec3} v2 - The second vector. @@ -205,7 +205,7 @@ public slots: glm::vec3 subtract(const glm::vec3& v1, const glm::vec3& v2) { return v1 - v2; } /**jsdoc - * Calculate the length of a vector + * Calculates the length of a vector * @function Vec3(0).length * @param {Vec3} v - The vector. * @returns {number} The length of the vector. @@ -213,7 +213,7 @@ public slots: float length(const glm::vec3& v) { return glm::length(v); } /**jsdoc - * Calculate the distance between two points. + * Calculates the distance between two points. * @function Vec3(0).distance * @param {Vec3} p1 - The first point. * @param {Vec3} p2 - The second point. @@ -231,16 +231,17 @@ public slots: float distance(const glm::vec3& v1, const glm::vec3& v2) { return glm::distance(v1, v2); } /**jsdoc - * Calculate the angle of rotation from one vector onto another, with the sign depending on a reference vector. + * Calculates the angle of rotation from one vector onto another, with the sign depending on a reference vector. * @function Vec3(0).orientedAngle * @param {Vec3} v1 - The first vector. * @param {Vec3} v2 - The second vector. * @param {Vec3} ref - Reference vector. - * @returns {number} The angle of rotation from the first vector to the second, in degrees, with a positive sign if the - * rotation axis aligns with the reference vector (has a positive dot product) otherwise a negative sign. - * @example Compare Vec3.angle() and Vec3.orientedAngle(). + * @returns {number} The angle of rotation from the first vector to the second, in degrees. The value is positive if the + * rotation axis aligns with the reference vector (has a positive dot product), otherwise the value is negative. + * @example Compare Vec3.getAngle() and Vec3.orientedAngle(). * var v1 = { x: 5, y: 0, z: 0 }; * var v2 = { x: 5, y: 0, z: 5 }; + * * var angle = Vec3.getAngle(v1, v2); * print(angle * 180 / Math.PI); // 45 * @@ -252,7 +253,7 @@ public slots: float orientedAngle(const glm::vec3& v1, const glm::vec3& v2, const glm::vec3& v3); /**jsdoc - * Normalize a vector so that its length is 1. + * Normalizes a vector so that its length is 1. * @function Vec3(0).normalize * @param {Vec3} v - The vector to normalize. * @returns {Vec3} The vector normalized to have a length of 1. @@ -265,11 +266,11 @@ public slots: glm::vec3 normalize(const glm::vec3& v) { return glm::normalize(v); }; /**jsdoc - * Calculate a linear interpolation between two vectors. + * Calculates a linear interpolation between two vectors. * @function Vec3(0).mix * @param {Vec3} v1 - The first vector. * @param {Vec3} v2 - The second vector. - * @param {number} factor - The interpolation factor in the range 0.0 to 1.0. + * @param {number} factor - The interpolation factor, range 0.0 – 1.0. * @returns {Vec3} The linear interpolation between the two vectors: (1 - factor) * v1 + factor * v2. * @example Linear interpolation between two vectors. * var v1 = { x: 10, y: 0, z: 0 }; @@ -280,7 +281,7 @@ public slots: glm::vec3 mix(const glm::vec3& v1, const glm::vec3& v2, float m) { return glm::mix(v1, v2, m); } /**jsdoc - * Print to the program log a text label followed by a vector value. + * Prints the vector to the program log, as a text label followed by the vector value. * @function Vec3(0).print * @param {string} label - The label to print. * @param {Vec3} v - The vector value to print. @@ -292,8 +293,9 @@ public slots: void print(const QString& label, const glm::vec3& v); /**jsdoc - * Test whether two vectors are equal. Note: The vectors must be exactly equal in order for - * true to be returned; it is often better to use {@link Vec3(0).withinEpsilon|withinEpsilon}. + * Tests whether two vectors are equal. + *

Note: The vectors must be exactly equal in order for true to be returned; it is often + * better to use {@link Vec3(0).withinEpsilon|withinEpsilon}.

* @function Vec3(0).equal * @param {Vec3} v1 - The first vector. * @param {Vec3} v2 - The second vector. @@ -301,6 +303,7 @@ public slots: * @example Vectors are only equal if exactly the same. * var v1 = { x: 10, y: 10, z: 10 }; * var v2 = { x: 10, y: 10, z: 10 }; + * * var equal = Vec3.equal(v1, v2); * print(equal); // true * @@ -311,17 +314,18 @@ public slots: bool equal(const glm::vec3& v1, const glm::vec3& v2) { return v1 == v2; } /**jsdoc - * Test whether two vectors are equal within a tolerance. Note: It is often better to use this function - * than {@link Vec3(0).equal|equal}. + * Tests whether two vectors are equal within a tolerance. + *

Note: It is often better to use this function than {@link Vec3(0).equal|equal}.

* @function Vec3(0).withinEpsilon * @param {Vec3} v1 - The first vector. * @param {Vec3} v2 - The second vector. * @param {number} epsilon - The maximum distance between the two vectors. * @returns {boolean} true if the distance between the points represented by the vectors is less than or equal - * to the epsilon, otherwise false. + * to epsilon, otherwise false. * @example Testing vectors for near equality. * var v1 = { x: 10, y: 10, z: 10 }; * var v2 = { x: 10, y: 10, z: 10.0005 }; + * * var equal = Vec3.equal(v1, v2); * print(equal); // false * @@ -331,11 +335,11 @@ public slots: bool withinEpsilon(const glm::vec3& v1, const glm::vec3& v2, float epsilon); /**jsdoc - * Calculate polar coordinates (elevation, azimuth, radius) that transform the unit z-axis vector onto a point. + * Calculates polar coordinates (elevation, azimuth, radius) that transform the unit z-axis vector onto a point. * @function Vec3(0).toPolar * @param {Vec3} p - The point to calculate the polar coordinates for. * @returns {Vec3} Vector of polar coordinates for the point: x elevation rotation about the x-axis in - * radians, y azimuth rotation about the y-axis in radians, and z scale. + * radians, y azimuth rotation about the y-axis in radians, and z radius. * @example Polar coordinates for a point. * var v = { x: 5, y: 2.5, z: 5 }; * var polar = Vec3.toPolar(v); @@ -347,10 +351,10 @@ public slots: glm::vec3 toPolar(const glm::vec3& v); /**jsdoc - * Calculate the coordinates of a point from polar coordinate transformation of the unit z-axis vector. + * Calculates the coordinates of a point from polar coordinate transformation of the unit z-axis vector. * @function Vec3(0).fromPolar * @param {Vec3} polar - The polar coordinates of a point: x elevation rotation about the x-axis in radians, - * y azimuth rotation about the y-axis in radians, and z scale. + * y azimuth rotation about the y-axis in radians, and z radius. * @returns {Vec3} The coordinates of the point. * @example Polar coordinates to Cartesian. * var polar = { x: -19.471 * Math.PI / 180, y: 45 * Math.PI / 180, z: 7.5 }; @@ -361,18 +365,17 @@ public slots: glm::vec3 fromPolar(const glm::vec3& polar); /**jsdoc - * Calculate the unit vector corresponding to polar coordinates elevation and azimuth transformation of the unit z-axis + * Calculates the unit vector corresponding to polar coordinates elevation and azimuth transformation of the unit z-axis * vector. * @function Vec3(0).fromPolar * @param {number} elevation - Rotation about the x-axis, in radians. * @param {number} azimuth - Rotation about the y-axis, in radians. * @returns {Vec3} Unit vector for the direction specified by elevation and azimuth. - * @example Polar coordinates to Cartesian. + * @example Polar coordinates to Cartesian coordinates. * var elevation = -19.471 * Math.PI / 180; * var rotation = 45 * Math.PI / 180; * var p = Vec3.fromPolar(elevation, rotation); * print(JSON.stringify(p)); // {"x":0.667,"y":0.333,"z":0.667} - * * p = Vec3.multiply(7.5, p); * print(JSON.stringify(p)); // {"x":5,"y":2.5,"z":5} */ @@ -380,7 +383,7 @@ public slots: glm::vec3 fromPolar(float elevation, float azimuth); /**jsdoc - * Calculate the angle between two vectors. + * Calculates the angle between two vectors. * @function Vec3(0).getAngle * @param {Vec3} v1 - The first vector. * @param {Vec3} v2 - The second vector. diff --git a/libraries/shared/src/RegisteredMetaTypes.h b/libraries/shared/src/RegisteredMetaTypes.h index 3e73ab6177..2ca7863ec6 100644 --- a/libraries/shared/src/RegisteredMetaTypes.h +++ b/libraries/shared/src/RegisteredMetaTypes.h @@ -100,7 +100,8 @@ glm::vec2 vec2FromVariant(const QVariant& object); * @property {number} x - X-coordinate of the vector. Synonyms: r, red. * @property {number} y - Y-coordinate of the vector. Synonyms: g, green. * @property {number} z - Z-coordinate of the vector. Synonyms: b, blue. -* @example Vec3s can be set in multiple ways and modified with their aliases, but still stringify in the same way +* @example Vec3 values can be set in multiple ways and modified with their aliases, but still stringify in the same +* way. * Entities.editEntity(, { position: { x: 1, y: 2, z: 3 }}); // { x: 1, y: 2, z: 3 } * Entities.editEntity(, { position: { r: 4, g: 5, b: 6 }}); // { x: 4, y: 5, z: 6 } * Entities.editEntity(, { position: { red: 7, green: 8, blue: 9 }}); // { x: 7, y: 8, z: 9 }