From 8b91e55c84520b7ebbee088bc369da46049c9330 Mon Sep 17 00:00:00 2001 From: David Williams Date: Sun, 9 Dec 2012 14:53:47 +0100 Subject: [PATCH] Changed documentation style to match that used by KDE/Kate (for Doxygen syntax highlighting) --- .../PolyVoxCore/include/PolyVoxCore/Vector.h | 60 +-- .../include/PolyVoxCore/Vector.inl | 376 +++++++++--------- 2 files changed, 218 insertions(+), 218 deletions(-) diff --git a/library/PolyVoxCore/include/PolyVoxCore/Vector.h b/library/PolyVoxCore/include/PolyVoxCore/Vector.h index 6181acb9..e38c04ee 100644 --- a/library/PolyVoxCore/include/PolyVoxCore/Vector.h +++ b/library/PolyVoxCore/include/PolyVoxCore/Vector.h @@ -36,36 +36,36 @@ freely, subject to the following restrictions: namespace PolyVox { /** - Represents a vector in space. - - This Vector class is templated on both size and data type. It is designed to be - generic but so far had only been tested with vectors of size 2 and 3. Also note - that some of the operations do not make sense with integer types, for example it - does not make conceptual sense to try and normalise an integer Vector. - - The elements of the Vector are accessed via the overloaded () operator which takes - an index indicating the element to fetch. They are set using the set() function which - takes an index indicating the element to set and a new value for that element. For - convienience, the functions getX(), setX(), getY(), setY(), getZ(), setZ(), getw() and setW() - do the same thing for the first 4 elements of the Vector. - - A variety of overloaded operators are also provided for comparison and arithmetic - operations. For most of these arithmetic operators only the unary versions are - documented below - however often binary versions are also generated by std::operators. - - Lastly, note that for convienience a set of typedefs are included for 2 and 3 dimensional - vectors with type float, double, int32_t, and uint32_t. They are used as follows: - - \code - Vector2DInt4 test(1,2); //Declares a 2 dimensional Vector of type int4. - \endcode - - Extra things to mention when I when I fill this out shortly: - Vector must have at least two elements. - Use of 'OperationType' - Floating point return values are always single precision - Component order is WYZW - */ + * Represents a vector in space. + * + * This Vector class is templated on both size and data type. It is designed to be + * generic but so far had only been tested with vectors of size 2 and 3. Also note + * that some of the operations do not make sense with integer types, for example it + * does not make conceptual sense to try and normalise an integer Vector. + * + * The elements of the Vector are accessed via the overloaded () operator which takes + * an index indicating the element to fetch. They are set using the set() function which + * takes an index indicating the element to set and a new value for that element. For + * convienience, the functions getX(), setX(), getY(), setY(), getZ(), setZ(), getw() and setW() + * do the same thing for the first 4 elements of the Vector. + * + * A variety of overloaded operators are also provided for comparison and arithmetic + * operations. For most of these arithmetic operators only the unary versions are + * documented below - however often binary versions are also generated by std::operators. + * + * Lastly, note that for convienience a set of typedefs are included for 2 and 3 dimensional + * vectors with type float, double, int32_t, and uint32_t. They are used as follows: + * + * \code + * Vector2DInt4 test(1,2); //Declares a 2 dimensional Vector of type int4. + * \endcode + * + * Extra things to mention when I when I fill this out shortly: + * Vector must have at least two elements. + * Use of 'OperationType' + * Floating point return values are always single precision + * Component order is WYZW + */ template class Vector { diff --git a/library/PolyVoxCore/include/PolyVoxCore/Vector.inl b/library/PolyVoxCore/include/PolyVoxCore/Vector.inl index cf8374ca..09501f18 100644 --- a/library/PolyVoxCore/include/PolyVoxCore/Vector.inl +++ b/library/PolyVoxCore/include/PolyVoxCore/Vector.inl @@ -25,17 +25,17 @@ namespace PolyVox { //-------------------------- Constructors, etc --------------------------------- /** - Creates a Vector object but does not initialise it. - */ + * Creates a Vector object but does not initialise it. + */ template Vector::Vector(void) { } /** - Creates a Vector object and initialises all components with the given value. - \param tFillValue The value to write to every component. - */ + * Creates a Vector object and initialises all components with the given value. + * \param tFillValue The value to write to every component. + */ template Vector::Vector(StorageType tFillValue) { @@ -46,10 +46,10 @@ namespace PolyVox } /** - Creates a Vector object and initialises it with given values. - \param x The X component to set. - \param y The Y component to set. - */ + * Creates a Vector object and initialises it with given values. + * \param x The X component to set. + * \param y The Y component to set. + */ template Vector::Vector(StorageType x, StorageType y) { @@ -62,11 +62,11 @@ namespace PolyVox } /** - Creates a Vector3D object and initialises it with given values. - \param x The X component to set. - \param y The Y component to set. - \param z the Z component to set. - */ + * Creates a Vector3D object and initialises it with given values. + * \param x The X component to set. + * \param y The Y component to set. + * \param z the Z component to set. + */ template Vector::Vector(StorageType x, StorageType y, StorageType z) { @@ -81,12 +81,12 @@ namespace PolyVox } /** - Creates a Vector3D object and initialises it with given values. - \param x The X component to set. - \param y The Y component to set. - \param z The Z component to set. - \param w The W component to set. - */ + * Creates a Vector3D object and initialises it with given values. + * \param x The X component to set. + * \param y The Y component to set. + * \param z The Z component to set. + * \param w The W component to set. + */ template Vector::Vector(StorageType x, StorageType y, StorageType z, StorageType w) { @@ -101,9 +101,9 @@ namespace PolyVox } /** - Copy constructor builds object based on object passed as parameter. - \param vector A reference to the Vector to be copied. - */ + * Copy constructor builds object based on object passed as parameter. + * \param vector A reference to the Vector to be copied. + */ template Vector::Vector(const Vector& vector) { @@ -111,14 +111,14 @@ namespace PolyVox } /** - This copy constructor allows casting between vectors with different data types. - It makes it possible to use code such as: - - Vector3DDouble v3dDouble(1.0,2.0,3.0); - Vector3DFloat v3dFloat = static_cast(v3dDouble); //Casting - - \param vector A reference to the Vector to be copied. - */ + * This copy constructor allows casting between vectors with different data types. + * It makes it possible to use code such as: + * + * Vector3DDouble v3dDouble(1.0,2.0,3.0); + * Vector3DFloat v3dFloat = static_cast(v3dDouble); //Casting + * + * \param vector A reference to the Vector to be copied. + */ template template Vector::Vector(const Vector& vector) @@ -130,8 +130,8 @@ namespace PolyVox } /** - Destroys the Vector. - */ + * Destroys the Vector. + */ template Vector::~Vector(void) { @@ -146,10 +146,10 @@ namespace PolyVox } /** - Assignment operator copies each element of first Vector to the second. - \param rhs Vector to assign to. - \return A reference to the result to allow chaining. - */ + * Assignment operator copies each element of first Vector to the second. + * \param rhs Vector to assign to. + * \return A reference to the result to allow chaining. + */ template Vector& Vector::operator=(const Vector& rhs) { @@ -162,11 +162,11 @@ namespace PolyVox } /** - Checks whether two Vectors are equal. - \param rhs The Vector to compare to. - \return true if the Vectors match. - \see operator!= - */ + * Checks whether two Vectors are equal. + * \param rhs The Vector to compare to. + * \return true if the Vectors match. + * \see operator!= + */ template inline bool Vector::operator==(const Vector &rhs) const { @@ -183,11 +183,11 @@ namespace PolyVox } /** - Checks whether two Vectors are not equal. - \param rhs The Vector to compare to. - \return true if the Vectors do not match. - \see operator== - */ + * Checks whether two Vectors are not equal. + * \param rhs The Vector to compare to. + * \return true if the Vectors do not match. + * \see operator== + */ template inline bool Vector::operator!=(const Vector &rhs) const { @@ -195,14 +195,14 @@ namespace PolyVox } /** - Checks whether this vector is less than the parameter. The metric is - meaningless but it allows Vectors to me used as key in sdt::map, etc. - This function is deprecated. You should specify a seperate comparator to the std:map if you need one. - \param rhs The Vector to compare to. - \return true if this is less than the parameter - \see operator!= - \deprecated - */ + * Checks whether this vector is less than the parameter. The metric is + * meaningless but it allows Vectors to me used as key in sdt::map, etc. + * This function is deprecated. You should specify a seperate comparator to the std:map if you need one. + * \param rhs The Vector to compare to. + * \return true if this is less than the parameter + * \see operator!= + * \deprecated + */ template inline bool Vector::operator<(const Vector &rhs) const { @@ -217,10 +217,10 @@ namespace PolyVox } /** - Addition operator adds corresponding elements of the two Vectors. - \param rhs The Vector to add - \return The resulting Vector. - */ + * Addition operator adds corresponding elements of the two Vectors. + * \param rhs The Vector to add + * \return The resulting Vector. + */ template inline Vector& Vector::operator+=(const Vector& rhs) { @@ -232,10 +232,10 @@ namespace PolyVox } /** - Subtraction operator subtracts corresponding elements of one Vector from the other. - \param rhs The Vector to subtract - \return The resulting Vector. - */ + * Subtraction operator subtracts corresponding elements of one Vector from the other. + * \param rhs The Vector to subtract + * \return The resulting Vector. + */ template inline Vector& Vector::operator-=(const Vector& rhs) { @@ -247,10 +247,10 @@ namespace PolyVox } /** - Multiplication operator multiplies corresponding elements of the two Vectors. - \param rhs The Vector to multiply by - \return The resulting Vector. - */ + * Multiplication operator multiplies corresponding elements of the two Vectors. + * \param rhs The Vector to multiply by + * \return The resulting Vector. + */ template inline Vector& Vector::operator*=(const Vector& rhs) { @@ -262,10 +262,10 @@ namespace PolyVox } /** - Division operator divides corresponding elements of one Vector by the other. - \param rhs The Vector to divide by - \return The resulting Vector. - */ + * Division operator divides corresponding elements of one Vector by the other. + * \param rhs The Vector to divide by + * \return The resulting Vector. + */ template inline Vector& Vector::operator/=(const Vector& rhs) { @@ -277,10 +277,10 @@ namespace PolyVox } /** - Multiplication operator multiplies each element of the Vector by a number. - \param rhs The number the Vector is multiplied by. - \return The resulting Vector. - */ + * Multiplication operator multiplies each element of the Vector by a number. + * \param rhs The number the Vector is multiplied by. + * \return The resulting Vector. + */ template inline Vector& Vector::operator*=(const StorageType& rhs) { @@ -292,10 +292,10 @@ namespace PolyVox } /** - Division operator divides each element of the Vector by a number. - \param rhs The number the Vector is divided by. - \return The resulting Vector. - */ + * Division operator divides each element of the Vector by a number. + * \param rhs The number the Vector is divided by. + * \return The resulting Vector. + */ template inline Vector& Vector::operator/=(const StorageType& rhs) { @@ -307,11 +307,11 @@ namespace PolyVox } /** - Addition operator adds corresponding elements of the two Vectors. - \param lhs The Vector to add to. - \param rhs The Vector to add. - \return The resulting Vector. - */ + * Addition operator adds corresponding elements of the two Vectors. + * \param lhs The Vector to add to. + * \param rhs The Vector to add. + * \return The resulting Vector. + */ template Vector operator+(const Vector& lhs, const Vector& rhs) { @@ -321,11 +321,11 @@ namespace PolyVox } /** - Subtraction operator subtracts corresponding elements of one Vector from the other. - \param lhs The Vector to subtract from. - \param rhs The Vector to subtract. - \return The resulting Vector. - */ + * Subtraction operator subtracts corresponding elements of one Vector from the other. + * \param lhs The Vector to subtract from. + * \param rhs The Vector to subtract. + * \return The resulting Vector. + */ template Vector operator-(const Vector& lhs, const Vector& rhs) { @@ -335,11 +335,11 @@ namespace PolyVox } /** - Multiplication operator mulitplies corresponding elements of the two Vectors. - \param lhs The Vector to multiply. - \param rhs The Vector to multiply by. - \return The resulting Vector. - */ + * Multiplication operator mulitplies corresponding elements of the two Vectors. + * \param lhs The Vector to multiply. + * \param rhs The Vector to multiply by. + * \return The resulting Vector. + */ template Vector operator*(const Vector& lhs, const Vector& rhs) { @@ -349,11 +349,11 @@ namespace PolyVox } /** - Division operator divides corresponding elements of one Vector by the other. - \param lhs The Vector to divide. - \param rhs The Vector to divide by. - \return The resulting Vector. - */ + * Division operator divides corresponding elements of one Vector by the other. + * \param lhs The Vector to divide. + * \param rhs The Vector to divide by. + * \return The resulting Vector. + */ template Vector operator/(const Vector& lhs, const Vector& rhs) { @@ -363,11 +363,11 @@ namespace PolyVox } /** - Multiplication operator multiplies each element of the Vector by a number. - \param lhs The Vector to multiply. - \param rhs The number the Vector is multiplied by. - \return The resulting Vector. - */ + * Multiplication operator multiplies each element of the Vector by a number. + * \param lhs The Vector to multiply. + * \param rhs The number the Vector is multiplied by. + * \return The resulting Vector. + */ template Vector operator*(const Vector& lhs, const StorageType& rhs) { @@ -377,11 +377,11 @@ namespace PolyVox } /** - Division operator divides each element of the Vector by a number. - \param lhs The Vector to divide. - \param rhs The number the Vector is divided by. - \return The resulting Vector. - */ + * Division operator divides each element of the Vector by a number. + * \param lhs The Vector to divide. + * \param rhs The number the Vector is divided by. + * \return The resulting Vector. + */ template Vector operator/(const Vector& lhs, const StorageType& rhs) { @@ -391,11 +391,11 @@ namespace PolyVox } /** - Enables the Vector to be used intuitively with output streams such as cout. - \param os The output stream to write to. - \param vector The Vector to write to the stream. - \return A reference to the output stream to allow chaining. - */ + * Enables the Vector to be used intuitively with output streams such as cout. + * \param os The output stream to write to. + * \param vector The Vector to write to the stream. + * \return A reference to the output stream to allow chaining. + */ template std::ostream& operator<<(std::ostream& os, const Vector& vector) { @@ -413,10 +413,10 @@ namespace PolyVox } /** - Returns the element at the given position. - \param index The index of the element to return. - \return The element. - */ + * Returns the element at the given position. + * \param index The index of the element to return. + * \return The element. + */ template inline StorageType Vector::getElement(uint32_t index) const { @@ -425,8 +425,8 @@ namespace PolyVox } /** - \return A const reference to the X component of a 1, 2, 3, or 4 dimensional Vector. - */ + * \return A const reference to the X component of a 1, 2, 3, or 4 dimensional Vector. + */ template inline StorageType Vector::getX(void) const { @@ -434,8 +434,8 @@ namespace PolyVox } /** - \return A const reference to the Y component of a 2, 3, or 4 dimensional Vector. - */ + * \return A const reference to the Y component of a 2, 3, or 4 dimensional Vector. + */ template inline StorageType Vector::getY(void) const { @@ -443,8 +443,8 @@ namespace PolyVox } /** - \return A const reference to the Z component of a 3 or 4 dimensional Vector. - */ + * \return A const reference to the Z component of a 3 or 4 dimensional Vector. + */ template inline StorageType Vector::getZ(void) const { @@ -456,8 +456,8 @@ namespace PolyVox } /** - \return A const reference to the W component of a 4 dimensional Vector. - */ + * \return A const reference to the W component of a 4 dimensional Vector. + */ template inline StorageType Vector::getW(void) const { @@ -469,9 +469,9 @@ namespace PolyVox } /** - \param index The index of the element to set. - \param tValue The new value for the element. - */ + * \param index The index of the element to set. + * \param tValue The new value for the element. + */ template inline void Vector::setElement(uint32_t index, StorageType tValue) { @@ -480,10 +480,10 @@ namespace PolyVox } /** - Sets several elements of a vector at once. - \param x The X component to set. - \param y The Y component to set. - */ + * Sets several elements of a vector at once. + * \param x The X component to set. + * \param y The Y component to set. + */ template inline void Vector::setElements(StorageType x, StorageType y) { @@ -493,11 +493,11 @@ namespace PolyVox } /** - Sets several elements of a vector at once. - \param x The X component to set. - \param y The Y component to set. - \param z The Z component to set. - */ + * Sets several elements of a vector at once. + * \param x The X component to set. + * \param y The Y component to set. + * \param z The Z component to set. + */ template inline void Vector::setElements(StorageType x, StorageType y, StorageType z) { @@ -510,12 +510,12 @@ namespace PolyVox } /** - Sets several elements of a vector at once. - \param x The X component to set. - \param y The Y component to set. - \param z The Z component to set. - \param w The W component to set. - */ + * Sets several elements of a vector at once. + * \param x The X component to set. + * \param y The Y component to set. + * \param z The Z component to set. + * \param w The W component to set. + */ template inline void Vector::setElements(StorageType x, StorageType y, StorageType z, StorageType w) { @@ -529,8 +529,8 @@ namespace PolyVox } /** - \param tX The new value for the X component of a 1, 2, 3, or 4 dimensional Vector. - */ + * \param tX The new value for the X component of a 1, 2, 3, or 4 dimensional Vector. + */ template inline void Vector::setX(StorageType tX) { @@ -538,8 +538,8 @@ namespace PolyVox } /** - \param tY The new value for the Y component of a 2, 3, or 4 dimensional Vector. - */ + * \param tY The new value for the Y component of a 2, 3, or 4 dimensional Vector. + */ template inline void Vector::setY(StorageType tY) { @@ -547,8 +547,8 @@ namespace PolyVox } /** - \param tZ The new value for the Z component of a 3 or 4 dimensional Vector. - */ + * \param tZ The new value for the Z component of a 3 or 4 dimensional Vector. + */ template inline void Vector::setZ(StorageType tZ) { @@ -559,8 +559,8 @@ namespace PolyVox } /** - \param tW The new value for the W component of a 4 dimensional Vector. - */ + * \param tW The new value for the W component of a 4 dimensional Vector. + */ template inline void Vector::setW(StorageType tW) { @@ -571,9 +571,9 @@ namespace PolyVox } /** - \note This function always returns a single precision floating point value, even when the StorageType is a double precision floating point value or an integer. - \return The length of the Vector. - */ + * \note This function always returns a single precision floating point value, even when the StorageType is a double precision floating point value or an integer. + * \return The length of the Vector. + */ template inline float Vector::length(void) const { @@ -581,8 +581,8 @@ namespace PolyVox } /** - \return The squared length of the Vector. - */ + * \return The squared length of the Vector. + */ template inline OperationType Vector::lengthSquared(void) const { @@ -595,14 +595,14 @@ namespace PolyVox } /** - This function is commutative, such that a.angleTo(b) == b.angleTo(a). The angle - returned is in radians and varies between 0 and 3.14(pi). It is always positive. - - \note This function always returns a single precision floating point value, even when the StorageType is a double precision floating point value or an integer. - - \param vector The Vector to find the angle to. - \return The angle between them in radians. - */ + * This function is commutative, such that a.angleTo(b) == b.angleTo(a). The angle + * returned is in radians and varies between 0 and 3.14(pi). It is always positive. + * + * \note This function always returns a single precision floating point value, even when the StorageType is a double precision floating point value or an integer. + * + * \param vector The Vector to find the angle to. + * \return The angle between them in radians. + */ template inline float Vector::angleTo(const Vector& vector) const { @@ -610,17 +610,17 @@ namespace PolyVox } /** - This function is used to calculate the cross product of two Vectors. - The cross product is the Vector which is perpendicular to the two - given Vectors. It is worth remembering that, unlike the dot product, - it is not commutative. E.g a.b != b.a. The cross product obeys the - right-hand rule such that if the two vectors are given by the index - finger and middle finger respectively then the cross product is given - by the thumb. - \param vector The vector to cross with this - \return The value of the cross product. - \see dot() - */ + * This function is used to calculate the cross product of two Vectors. + * The cross product is the Vector which is perpendicular to the two + * given Vectors. It is worth remembering that, unlike the dot product, + * it is not commutative. E.g a.b != b.a. The cross product obeys the + * right-hand rule such that if the two vectors are given by the index + * finger and middle finger respectively then the cross product is given + * by the thumb. + * \param vector The vector to cross with this + * \return The value of the cross product. + * \see dot() + */ template inline Vector Vector::cross(const Vector& vector) const { @@ -631,12 +631,12 @@ namespace PolyVox } /** - Calculates the dot product of the Vector and the parameter. - This function is commutative, such that a.dot(b) == b.dot(a). - \param rhs The Vector to find the dot product with. - \return The value of the dot product. - \see cross() - */ + * Calculates the dot product of the Vector and the parameter. + * This function is commutative, such that a.dot(b) == b.dot(a). + * \param rhs The Vector to find the dot product with. + * \return The value of the dot product. + * \see cross() + */ template inline OperationType Vector::dot(const Vector& rhs) const { @@ -649,12 +649,12 @@ namespace PolyVox } /** - Divides the i, j, and k components by the length to give a Vector of length 1.0. If the vector is - very short (or zero) then a divide by zero may cause elements to take on invalid values. You may - want to check for this before normalising. - - \note You should not attempt to normalise a vector whose StorageType is an integer. - */ + * Divides the i, j, and k components by the length to give a Vector of length 1.0. If the vector is + * very short (or zero) then a divide by zero may cause elements to take on invalid values. You may + * want to check for this before normalising. + * + * \note You should not attempt to normalise a vector whose StorageType is an integer. + */ template inline void Vector::normalise(void) {