Documentation for EulerAngles + change Return of Set

Former-commit-id: 7e269b89e880156d66d92cff202095c4e30f344d

include/Nazara/Math/Config.hpp

@@ -28,15 +28,15 @@
 #ifndef NAZARA_CONFIG_MATH_HPP
 #define NAZARA_CONFIG_MATH_HPP
 
-/// Chaque modification d'un paramètre du module nécessite une recompilation de celui-ci
+/// Each modification of a paramater of the module needs a recompilation of the unit
 
-// Définit le radian comme l'unité utilisée pour les angles
+// Define the radian as unit for angles
 #define NAZARA_MATH_ANGLE_RADIAN 0
 
-// Optimise automatiquement les opérations entre matrices affines (Demande plusieurs comparaisons pour déterminer si une matrice est affine)
+// Optimize automatically the operation on affine matrices (Ask several comparisons to determine if the matrix is affine)
 #define NAZARA_MATH_MATRIX4_CHECK_AFFINE 0
 
-// Active les tests de sécurité basés sur le code (Conseillé pour le développement)
+// Enable tests of security based on the code (Advised for the developpement)
 #define NAZARA_MATH_SAFE 1
 
 #endif // NAZARA_CONFIG_MATH_HPP

include/Nazara/Math/EulerAngles.hpp

@@ -28,14 +28,14 @@ namespace Nz
 
 			void MakeZero();
 
-			void Normalize();
+			EulerAngles& Normalize();
 
-			void Set(T P, T Y, T R);
+			EulerAngles& Set(T P, T Y, T R);
-			void Set(const T angles[3]);
+			EulerAngles& Set(const T angles[3]);
-			void Set(const EulerAngles<T>& angles);
+			EulerAngles& Set(const EulerAngles<T>& angles);
-			//void Set(const Matrix3<T>& mat);
+			//EulerAngles& Set(const Matrix3<T>& mat);
-			void Set(const Quaternion<T>& quat);
+			EulerAngles& Set(const Quaternion<T>& quat);
-			template<typename U> void Set(const EulerAngles<U>& angles);
+			template<typename U> EulerAngles& Set(const EulerAngles<U>& angles);
 
 			//Matrix3<T> ToRotationMatrix() const;
 			Quaternion<T> ToQuaternion() const;

include/Nazara/Math/EulerAngles.inl

@@ -14,24 +14,58 @@
 
 namespace Nz
 {
+
+	/*!
+	* \class Nz::Vector4<T>
+	* \brief Math class that represents an Euler angle. Those describe a rotation transformation by rotating an object on its various axes in specified amounts per axis, and a specified axis order
+	*
+	* \remark Rotation are "left-handed", it means that you take your left hand, put your thumb finger in the direction you want and you other fingers represent the way of rotating
+	*/
+
+	/*!
+	* \brief Constructs a EulerAngles<T> object from its components
+	*
+	* \param P Pitch component = X axis
+	* \param Y Yaw component = Y axis
+	* \param R Roll component = Z axis
+	*/
+
 	template<typename T>
 	EulerAngles<T>::EulerAngles(T P, T Y, T R)
 	{
 		Set(P, Y, R);
 	}
 
+	/*!
+	* \brief Constructs a EulerAngles<T> object from an array of three elements
+	*
+	* \param angles[3] angles[0] is pitch component, angles[1] is yaw component and angles[2] is roll component
+	*/
+
 	template<typename T>
 	EulerAngles<T>::EulerAngles(const T angles[3])
 	{
 		Set(angles);
 	}
 
+	/*!
+	* \brief Constructs a EulerAngles<T> object from a quaternion
+	*
+	* \param quat Quaternion representing a rotation of space
+	*/
+
 	template<typename T>
 	EulerAngles<T>::EulerAngles(const Quaternion<T>& quat)
 	{
 		Set(quat);
 	}
 
+	/*!
+	* \brief Constructs a EulerAngles<T> object from another type of EulerAngles
+	*
+	* \param angles EulerAngles of type U to convert to type T
+	*/
+
 	template<typename T>
 	template<typename U>
 	EulerAngles<T>::EulerAngles(const EulerAngles<U>& angles)
@@ -39,57 +73,125 @@ namespace Nz
 		Set(angles);
 	}
 
+	/*!
+	* \brief Makes the euler angle (0, 0, 0)
+	* \return A reference to this euler angle with components (0, 0, 0)
+	*
+	* \see Zero
+	*/
+
 	template<typename T>
 	void EulerAngles<T>::MakeZero()
 	{
 		Set(F(0.0), F(0.0), F(0.0));
 	}
 
+	/*!
+	* \brief Normalizes the euler angle
+	* \return A reference to this euler angle with has been normalized
+	*
+	* \remark Normalization depends on NAZARA_MATH_ANGLE_RADIAN, between 0..2*pi
+	*
+	* \see NormalizeAngle
+	*/
+
 	template<typename T>
-	void EulerAngles<T>::Normalize()
+	EulerAngles<T>& EulerAngles<T>::Normalize()
 	{
 		pitch = NormalizeAngle(pitch);
 		yaw = NormalizeAngle(yaw);
 		roll = NormalizeAngle(roll);
+
+		return *this;
 	}
 
+	/*!
+	* \brief Sets the components of the euler angle
+	* \return A reference to this euler angle
+	*
+	* \param P Pitch component = X axis
+	* \param Y Yaw component = Y axis
+	* \param R Roll component = Z axis
+	*/
+
 	template<typename T>
-	void EulerAngles<T>::Set(T P, T Y, T R)
+	EulerAngles<T>& EulerAngles<T>::Set(T P, T Y, T R)
 	{
 		pitch = P;
 		yaw = Y;
 		roll = R;
+
+		return *this;
 	}
 
+	/*!
+	* \brief Sets the components of the euler angle from an array of three elements
+	* \return A reference to this euler angle
+	*
+	* \param angles[3] angles[0] is pitch component, angles[1] is yaw component and angles[2] is roll component
+	*/
+
 	template<typename T>
-	void EulerAngles<T>::Set(const T angles[3])
+	EulerAngles<T>& EulerAngles<T>::Set(const T angles[3])
 	{
 		pitch = angles[0];
 		yaw = angles[1];
 		roll = angles[2];
+
+		return *this;
 	}
 
+	/*!
+	* \brief Sets the components of the euler angle from another euler angle
+	* \return A reference to this euler angle
+	*
+	* \param angles The other euler angle
+	*/
+
 	template<typename T>
-	void EulerAngles<T>::Set(const EulerAngles& angles)
+	EulerAngles<T>& EulerAngles<T>::Set(const EulerAngles& angles)
 	{
 		std::memcpy(this, &angles, sizeof(EulerAngles));
+
+		return *this;
 	}
 
+	/*!
+	* \brief Sets the components of the euler angle from a quaternion
+	* \return A reference to this euler angle
+	*
+	* \param quat Quaternion representing a rotation of space
+	*/
+
 	template<typename T>
-	void EulerAngles<T>::Set(const Quaternion<T>& quat)
+	EulerAngles<T>& EulerAngles<T>::Set(const Quaternion<T>& quat)
 	{
-		Set(quat.ToEulerAngles());
+		return Set(quat.ToEulerAngles());
 	}
 
+	/*!
+	* \brief Sets the components of the euler angle from another type of EulerAngles
+	* \return A reference to this euler angle
+	*
+	* \param angles EulerAngles of type U to convert its components
+	*/
+
 	template<typename T>
 	template<typename U>
-	void EulerAngles<T>::Set(const EulerAngles<U>& angles)
+	EulerAngles<T>& EulerAngles<T>::Set(const EulerAngles<U>& angles)
 	{
 		pitch = F(angles.pitch);
 		yaw = F(angles.yaw);
 		roll = F(angles.roll);
+
+		return *this;
 	}
 
+	/*!
+	* \brief Converts the euler angle to quaternion
+	* \return A Quaternion which represents the rotation of this euler angle
+	*/
+
 	template<typename T>
 	Quaternion<T> EulerAngles<T>::ToQuaternion() const
 	{
@@ -102,11 +204,16 @@ namespace Nz
 		T s3 = std::sin(ToRadians(pitch) / F(2.0));
 
 		return Quaternion<T>(c1 * c2 * c3 - s1 * s2 * s3,
-							   s1 * s2 * c3 + c1 * c2 * s3,
+		                     s1 * s2 * c3 + c1 * c2 * s3,
-							   s1 * c2 * c3 + c1 * s2 * s3,
+		                     s1 * c2 * c3 + c1 * s2 * s3,
-							   c1 * s2 * c3 - s1 * c2 * s3);
+		                     c1 * s2 * c3 - s1 * c2 * s3);
 	}
 
+	/*!
+	* \brief Gives a string representation
+	* \return A string representation of the object: "EulerAngles(pitch, yaw, roll)"
+	*/
+
 	template<typename T>
 	String EulerAngles<T>::ToString() const
 	{
@@ -115,22 +222,43 @@ namespace Nz
 		return ss << "EulerAngles(" << pitch << ", " << yaw << ", " << roll << ')';
 	}
 
+	/*!
+	* \brief Adds the components of the euler angle with other euler angle
+	* \return A euler angle where components are the sum of this euler angle and the other one
+	*
+	* \param angles The other euler angle to add components with
+	*/
+
 	template<typename T>
 	EulerAngles<T> EulerAngles<T>::operator+(const EulerAngles& angles) const
 	{
 		return EulerAngles(pitch + angles.pitch,
-							 yaw + angles.yaw,
+		                   yaw + angles.yaw,
-							 roll + angles.roll);
+		                   roll + angles.roll);
 	}
 
+	/*!
+	* \brief Substracts the components of the euler angle with other euler angle
+	* \return A euler angle where components are the difference of this euler angle and the other one
+	*
+	* \param angles The other euler angle to substract components with
+	*/
+
 	template<typename T>
 	EulerAngles<T> EulerAngles<T>::operator-(const EulerAngles& angles) const
 	{
 		return EulerAngles(pitch - angles.pitch,
-							 yaw - angles.yaw,
+		                   yaw - angles.yaw,
-							 roll - angles.roll);
+		                   roll - angles.roll);
 	}
 
+	/*!
+	* \brief Adds the components of other euler angle to this euler angle
+	* \return A reference to this euler angle where components are the sum of this euler angle and the other one
+	*
+	* \param angles The other euler angle to add components with
+	*/
+
 	template<typename T>
 	EulerAngles<T>& EulerAngles<T>::operator+=(const EulerAngles& angles)
 	{
@@ -141,6 +269,13 @@ namespace Nz
 		return *this;
 	}
 
+	/*!
+	* \brief Substracts the components of other euler angle to this euler angle
+	* \return A reference to this euler angle where components are the difference of this euler angle and the other one
+	*
+	* \param angle The other euler angle to substract components with
+	*/
+
 	template<typename T>
 	EulerAngles<T>& EulerAngles<T>::operator-=(const EulerAngles& angles)
 	{
@@ -151,20 +286,41 @@ namespace Nz
 		return *this;
 	}
 
+	/*!
+	* \brief Compares the euler angle to other one
+	* \return true if the euler angles are the same
+	*
+	* \param angles Other euler angle to compare with
+	*/
+
 	template<typename T>
 	bool EulerAngles<T>::operator==(const EulerAngles& angles) const
 	{
 		return NumberEquals(pitch, angles.pitch) &&
-			   NumberEquals(yaw, angles.yaw) &&
+		       NumberEquals(yaw, angles.yaw) &&
-			   NumberEquals(roll, angles.roll);
+		       NumberEquals(roll, angles.roll);
 	}
 
+	/*!
+	* \brief Compares the euler angle to other one
+	* \return false if the euler angles are the same
+	*
+	* \param angles Other euler angle to compare with
+	*/
+
 	template<typename T>
 	bool EulerAngles<T>::operator!=(const EulerAngles& angles) const
 	{
 		return !operator==(angles);
 	}
 
+	/*!
+	* \brief Shorthand for the euler angle (0, 0, 0)
+	* \return A euler angle with components (0, 0, 0)
+	*
+	* \see MakeZero
+	*/
+
 	template<typename T>
 	EulerAngles<T> EulerAngles<T>::Zero()
 	{
@@ -175,6 +331,14 @@ namespace Nz
 	}
 }
 
+/*!
+* \brief Output operator
+* \return The stream
+*
+* \param out The stream
+* \param angles The euler angle to output
+*/
+
 template<typename T>
 std::ostream& operator<<(std::ostream& out, const Nz::EulerAngles<T>& angles)
 {