From 5673cf26568673e9c246b7c9d38e101f8cda5eda Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Sat, 16 Feb 2013 20:53:56 +0100 Subject: [PATCH] Math: better documentation for vector/quat constructors. --- src/Math/DualQuaternion.h | 6 ++++-- src/Math/Point2D.h | 21 ++++++++++++++------- src/Math/Point3D.h | 22 ++++++++++++++-------- src/Math/Quaternion.h | 24 ++++++++++++++++++------ src/Math/Vector.h | 8 +++++++- src/Math/Vector2.h | 6 ++++-- src/Math/Vector3.h | 13 ++++++++----- src/Math/Vector4.h | 14 ++++++++------ 8 files changed, 77 insertions(+), 37 deletions(-) diff --git a/src/Math/DualQuaternion.h b/src/Math/DualQuaternion.h index 0b399b4f3..1f060e9e5 100644 --- a/src/Math/DualQuaternion.h +++ b/src/Math/DualQuaternion.h @@ -64,7 +64,9 @@ template class DualQuaternion: public Dual> { /** * @brief Default constructor * - * All components set to zero except real scalar part, which is `1`. + * @f[ + * \hat q = [\boldsymbol 0, 1] + \epsilon [\boldsymbol 0, 0] + * @f] * @todoc Remove workaround when Doxygen is predictable */ #ifdef DOXYGEN_GENERATING_OUTPUT @@ -148,7 +150,7 @@ template class DualQuaternion: public Dual> { * @brief Conjugated dual quaternion * * Both quaternion and dual conjugation. @f[ - * \overline{\hat q^*} = q_0^* - \epsilon q_\epsilon^* = q_0^* + \epsilon [\boldsymbol q_{\epsilon V}, -q_S] + * \overline{\hat q^*} = q_0^* - \epsilon q_\epsilon^* = q_0^* + \epsilon [\boldsymbol q_{V \epsilon}, -q_{S \epsilon}] * @f] * @see quaternionConjugated(), dualConjugated(), Quaternion::conjugated(), * Dual::conjugated() diff --git a/src/Math/Point2D.h b/src/Math/Point2D.h index 6172707ba..967a91692 100644 --- a/src/Math/Point2D.h +++ b/src/Math/Point2D.h @@ -37,29 +37,36 @@ template class Point2D: public Vector3 { /** * @brief Default constructor * - * X and Y components are set to zero, Z is set to one. + * @f[ + * \boldsymbol p = (0, 0, 1)^T + * @f] */ inline constexpr /*implicit*/ Point2D(): Vector3(T(0), T(0), T(1)) {} /** * @brief Constructor - * @param x X component - * @param y Y component - * @param z Z component + * + * @f[ + * \boldsymbol p = (x, y, z)^T + * @f] */ inline constexpr /*implicit*/ Point2D(T x, T y, T z = T(1)): Vector3(x, y, z) {} /** * @brief Constructor - * @param xy Two-component vector - * @param z Z component + * + * @f[ + * \boldsymbol p = (v_x, v_y, z)^T + * @f] */ inline constexpr /*implicit*/ Point2D(const Vector2& xy, T z): Vector3(xy, z) {} /** * @brief Construct 2D point from 2D vector * - * Z component is set to `1`. + * @f[ + * \boldsymbol p = (v_x, v_y, 1)^T + * @f] */ inline constexpr explicit Point2D(const Vector2& xy): Vector3(xy, T(1)) {} diff --git a/src/Math/Point3D.h b/src/Math/Point3D.h index a30e9c8ff..fbe97faa3 100644 --- a/src/Math/Point3D.h +++ b/src/Math/Point3D.h @@ -37,30 +37,36 @@ template class Point3D: public Vector4 { /** * @brief Default constructor * - * X, Y and Z components are set to zero, W is set to one. + * @f[ + * \boldsymbol p = (0, 0, 0, 1)^T + * @f] */ inline constexpr /*implicit*/ Point3D(): Vector4(T(0), T(0), T(0), T(1)) {} /** * @brief Constructor - * @param x X component - * @param y Y component - * @param z Z component - * @param w W component + * + * @f[ + * \boldsymbol p = (x, y, z, w)^T + * @f] */ inline constexpr /*implicit*/ Point3D(T x, T y, T z, T w = T(1)): Vector4(x, y, z, w) {} /** * @brief Constructor - * @param xyz Three-component vector - * @param w W component + * + * @f[ + * \boldsymbol p = (v_x, v_y, v_z, w)^T + * @f] */ inline constexpr /*implicit*/ Point3D(const Vector3& xyz, T w): Vector4(xyz, w) {} /** * @brief Construct 3D point from 3D vector * - * W component is set to `1`. + * @f[ + * \boldsymbol p = (v_x, v_y, v_z, 1)^T + * @f] */ inline constexpr explicit Point3D(const Vector3& xyz): Vector4(xyz, T(1)) {} diff --git a/src/Math/Quaternion.h b/src/Math/Quaternion.h index a25049370..e26ce38df 100644 --- a/src/Math/Quaternion.h +++ b/src/Math/Quaternion.h @@ -124,17 +124,28 @@ template class Quaternion { /** * @brief Default constructor * - * %Vector part is set to zero, scalar part to `1`. + * @f[ + * q = [\boldsymbol 0, 1] + * @f] */ inline constexpr /*implicit*/ Quaternion(): _scalar(T(1)) {} - /** @brief Create quaternion from vector and scalar */ + /** + * @brief Construct quaternion from vector and scalar + * + * @f[ + * q = [\boldsymbol v, s] + * @f] + */ inline constexpr /*implicit*/ Quaternion(const Vector3& vector, T scalar): _vector(vector), _scalar(scalar) {} /** - * @brief Create quaternion from vector + * @brief Construct quaternion from vector * - * Scalar is set to `0`. + * To be used in transformations later. @f[ + * q = [\boldsymbol v, 0] + * @f] + * @see rotateVector(), rotateVectorNormalized() */ inline constexpr explicit Quaternion(const Vector3& vector): _vector(vector), _scalar(T(0)) {} @@ -388,10 +399,10 @@ template class Quaternion { /** * @brief Rotate vector with quaternion * - * @f[ + * See rotateVectorNormalized(), which is faster for normalized + * quaternions. @f[ * v' = qvq^{-1} = q [\boldsymbol v, 0] q^{-1} * @f] - * @see rotateVectorNormalized() */ inline Vector3 rotateVector(const Vector3& vector) const { return ((*this)*Quaternion(vector)*inverted()).vector(); @@ -404,6 +415,7 @@ template class Quaternion { * normalized. @f[ * v' = qvq^{-1} = qvq^* = q [\boldsymbol v, 0] q^* * @f] + * @see DualQuaternion::transformVectorNormalized() */ inline Vector3 rotateVectorNormalized(const Vector3& vector) const { CORRADE_ASSERT(MathTypeTraits::equals(dot(), T(1)), diff --git a/src/Math/Vector.h b/src/Math/Vector.h index edc480ec2..3cc332854 100644 --- a/src/Math/Vector.h +++ b/src/Math/Vector.h @@ -90,7 +90,13 @@ template class Vector { return std::acos(dot(normalizedA, normalizedB)); } - /** @brief Construct zero-filled vector */ + /** + * @brief Default constructor + * + * @f[ + * \boldsymbol v = \boldsymbol 0 + * @f] + */ inline constexpr /*implicit*/ Vector(): _data() {} /** @todo Creating Vector from combination of vector and scalar types */ diff --git a/src/Math/Vector2.h b/src/Math/Vector2.h index 2fa7116c2..371788021 100644 --- a/src/Math/Vector2.h +++ b/src/Math/Vector2.h @@ -79,8 +79,10 @@ template class Vector2: public Vector<2, T> { /** * @brief Constructor - * @param x X component - * @param y Y component + * + * @f[ + * \boldsymbol v = (x, y)^T + * @f] */ inline constexpr /*implicit*/ Vector2(T x, T y): Vector<2, T>(x, y) {} diff --git a/src/Math/Vector3.h b/src/Math/Vector3.h index a2ad90872..9c1996bab 100644 --- a/src/Math/Vector3.h +++ b/src/Math/Vector3.h @@ -112,16 +112,19 @@ template class Vector3: public Vector<3, T> { /** * @brief Constructor - * @param x X component - * @param y Y component - * @param z Z component + * + * @f[ + * \boldsymbol v = (x, y, z)^T + * @f] */ inline constexpr /*implicit*/ Vector3(T x, T y, T z): Vector<3, T>(x, y, z) {} /** * @brief Constructor - * @param xy Two-component vector - * @param z Z component + * + * @f[ + * \boldsymbol v = (v_x, v_y, z)^T + * @f] */ inline constexpr /*implicit*/ Vector3(const Vector2& xy, T z): Vector<3, T>(xy[0], xy[1], z) {} diff --git a/src/Math/Vector4.h b/src/Math/Vector4.h index 329a96d94..29b4dc829 100644 --- a/src/Math/Vector4.h +++ b/src/Math/Vector4.h @@ -42,17 +42,19 @@ template class Vector4: public Vector<4, T> { /** * @brief Constructor - * @param x X component - * @param y Y component - * @param z Z component - * @param w W component + * + * @f[ + * \boldsymbol v = (x, y, z, w)^T + * @f] */ inline constexpr /*implicit*/ Vector4(T x, T y, T z, T w): Vector<4, T>(x, y, z, w) {} /** * @brief Constructor - * @param xyz Three-component vector - * @param w W component + * + * @f[ + * \boldsymbol v = (v_x, v_y, v_z, w)^T + * @f] */ inline constexpr /*implicit*/ Vector4(const Vector3& xyz, T w): Vector<4, T>(xyz[0], xyz[1], xyz[2], w) {}