Final commit for docs and tests in pimathvector.h

libs/main/math/pimathvector.h

@@ -52,7 +52,7 @@ public:
 	PIMathVectorT() {resize();}
 
 	/**
-	* @brief Constructor that fills a vector "PIMathVectorT" with the values ​​of another vector "PIVector"
+	* @brief Constructor that fills a vector PIMathVectorT with the values ​​of another vector "PIVector"
 	*
 	* @param val vector of type PIVector which is identified PIMathVectorT
 	* @return vector of type PIMathVectorT with values ​​of vector val
@@ -60,9 +60,10 @@ public:
 	PIMathVectorT(const PIVector<Type> & val) {resize(); PIMV_FOR(i, 0) c[i] = val[i];}
 
 	/**
-	* @brief Constructor that fills a vector "PIMathVectorT" with the subtraction of two vectors
+	* @brief Constructor that fills a vector PIMathVectorT with the subtraction of two vectors
 	*
-	* @param st vector of type PIMathVect	* @param fn vector of type PIMathVectorT
+	* @param st vector of type PIMathVectorT
+	* @param fn vector of type PIMathVectorT
 	* @return vector of type PIMathVectorT with values subtraction vectors "fn" and "st"
 	*/
 	PIMathVectorT(const _CVector & st, const _CVector & fn) {resize(); set(st, fn);}
@@ -78,7 +79,7 @@ public:
 	* @brief Method that fills a vector with a value
 	*
 	* @param v value of which the vector is filled
-	* @return vector of type PIMathVector filled with "v"
+	* @return vector of type PIMathVectorT filled with "v"
 	*/
 	_CVector & fill(const Type & v) {PIMV_FOR(i, 0) c[i] = v; return *this;}
 
@@ -139,7 +140,8 @@ public:
 	/**
 	* @brief Method that returns the sin of the current vector and vector "v". Works only with vectors which consists of 3 elements
 	*
-	* @param v vector of type PIMathVectorT	 * @return sin value of the angle between two vector
+	* @param v vector of type PIMathVectorT
+	* @return sin value of the angle between two vector
 	*/
 	Type angleSin(const _CVector & v) const {Type tv = angleCos(v); return sqrt(Type(1) - tv * tv);}
 
@@ -208,7 +210,7 @@ public:
 	/**
 	* @brief Method which checks if every elements of vector are zeros
 	*
-	* @return true if vector is null, else false
+	* @return true if vector is zero, else false
 	*/
 	bool isNull() const {PIMV_FOR(i, 0) if (c[i] != Type(0)) return false; return true;}
 
@@ -298,7 +300,7 @@ public:
 	*/
 	void operator *=(const Type & v) {PIMV_FOR(i, 0) c[i] *= v;}
 
-
+	/**
 	* @brief Multiplication assignment with vector "v"
 	*
 	* @param v vector for the multiplication assigment
@@ -430,29 +432,106 @@ private:
 
 };
 
+/**
+* @brief Inline operator which returns vector multiplication with value "x"
+*
+* @param x value for the multiplication
+* @param v vector for the multiplication
+* @return resulting vector
+*/
 template<uint Size, typename Type>
 inline PIMathVectorT<Size, Type> operator *(const Type & x, const PIMathVectorT<Size, Type> & v) {
 	return v * x;
 }
 
+/**
+* @brief Inline operator for outputting the vector to the console
+*
+* @param s PICout type
+* @param the vector type PIMathVectorT that we print to the console
+* @return PIMathVectorT printed to the console
+*/
 template<uint Size, typename Type>
 inline PICout operator <<(PICout s, const PIMathVectorT<Size, Type> & v) {s << "{"; PIMV_FOR(i, 0) {s << v[i]; if (i < Size - 1) s << ", ";} s << "}"; return s;}
+
+/**
+* @brief Inline operator checking if the cross product is zero. Works only with vector containing three elements, otherwise returns current vector
+*
+* @param f vector of the first operand
+* @param s vector of the second operand
+* @return true if the cross product is zero, else false
+*/
 template<uint Size, typename Type>
 inline bool operator ||(const PIMathVectorT<Size, Type> & f, const PIMathVectorT<Size, Type> & s) {return (f * s).isNull();}
+
+/**
+* @brief Inline function which takes the square root of each element in the vector
+*
+* @param v vector of whose elements the square root is taken
+* @return resulting vector
+*/
 template<uint Size, typename Type>
 inline PIMathVectorT<Size, Type> sqrt(const PIMathVectorT<Size, Type> & v) {PIMathVectorT<Size, Type> ret; PIMV_FOR(i, 0) {ret[i] = sqrt(v[i]);} return ret;}
+
+/**
+* @brief Inline function which squares each element of the vector
+*
+* @param v vector whose elements are squared
+* @return resulting vector
+*/
 template<uint Size, typename Type>
 inline PIMathVectorT<Size, Type> sqr(const PIMathVectorT<Size, Type> & v) {PIMathVectorT<Size, Type> ret; PIMV_FOR(i, 0) {ret[i] = sqr(v[i]);} return ret;}
 
+/**
+* @brief Inline operator for serializing a vector into a PIByteArray
+*
+* @param s PIByteArray type
+* @param v PIMathVectorT type
+* @return PIBiteArray serialized PIMathVectorT
+*/
 template<uint Size, typename Type>
 inline PIByteArray & operator <<(PIByteArray & s, const PIMathVectorT<Size, Type> & v) {for (uint i = 0; i < Size; ++i) s << v[i]; return s;}
+
+/**
+* @brief Inline operator to deserialize vector from PIByteArray
+*
+* @param s PIByteArray type
+* @param v PIMathVector type
+* @return PIMathVector deserialized from PIByteArray
+*/
 template<uint Size, typename Type>
 inline PIByteArray & operator >>(PIByteArray & s, PIMathVectorT<Size, Type> & v) {for (uint i = 0; i < Size; ++i) s >> v[i]; return s;}
 
+/**
+* @brief Inline function which returns vector size 2 and type of T
+*
+* @param x first element of vector
+* @param y second element of vector
+* @return resulting vector
+*/
 template<typename T>
 inline PIMathVectorT<2u, T> createVectorT2(T x, T y) {return PIMathVectorT<2u, T>(PIVector<T>() << x << y);}
+
+/**
+* @brief Inline function which returns vector size 3 and type of T
+*
+* @param x first element of vector
+* @param y second element of vector
+* @param z third element of vector
+* @return resulting vector
+*/
 template<typename T>
 inline PIMathVectorT<3u, T> createVectorT3(T x, T y, T z) {return PIMathVectorT<3u, T>(PIVector<T>() << x << y << z);}
+
+/**
+* @brief Inline function which returns vector size 4 and type of T
+*
+* @param x first element of vector
+* @param y second element of vector
+* @param z third element of vector
+* @param w fouth element of vector
+* @return resulting vector
+*/
 template<typename T>
 inline PIMathVectorT<4u, T> createVectorT4(T x, T y, T z, T w) {return PIMathVectorT<4u, T>(PIVector<T>() << x << y << z << w);}
 
@@ -478,69 +557,389 @@ typedef PIMathVectorT<4u, double> PIMathVectorT4d;
 
 #define PIMV_FOR(v, s) for (uint v = s; v < c.size(); ++v)
 
+//! \brief A class that works with vector operations, the input data of which is the data type of the vector
+//! @tparam Type is the data type of the vector. There are can be basic C++ language data and different classes where the arithmetic operators(=, +=, -=, *=, /=, ==, !=, +, -, *, /)
+//!  of the C++ language are implemented
 template<typename Type>
 class PIP_EXPORT PIMathVector {
 	typedef PIMathVector<Type> _CVector;
 	template<typename TypeOp> friend PIByteArray & operator <<(PIByteArray & s, const PIMathVector<TypeOp> & v);
 	template<typename TypeOp> friend PIByteArray & operator >>(PIByteArray & s, PIMathVector<TypeOp> & v);
 public:
+	/**
+	* @brief Constructor that calls the resize method
+	*
+	* @param size vector dimension
+	* @return resized vector of type PIMathMatrix
+	*/
 	PIMathVector(const uint size = 0) {c.resize(size);}
+
+	/**
+	* @brief Constructor that fills a vector PIMathVector with the values ​​of another vector "PIVector"
+	*
+	* @param val vector of type PIVector which is identified PIMathVector
+	* @return vector of type PIMathVector with values ​​of vector val
+	*/
 	PIMathVector(const PIVector<Type> & val) {c.resize(val.size()); PIMV_FOR(i, 0) c[i] = val[i];}
+
+	/**
+	* @brief Constructor that fills a vector PIMathVector with the subtraction of two vectors
+	*
+	* @param st vector of type PIMathVector
+	* @param fn vector of type PIMathVector
+	* @return vector of type PIMathVectorT with values subtraction vectors "fn" and "st"
+	*/
 	PIMathVector(const _CVector & st, const _CVector & fn) {c.resize(st.size()); PIMV_FOR(i, 0) c[i] = fn[i] - st[i];}
 
+	/**
+	* @brief Method which returns size of the vector
+	*
+	* @return type uint shows number of elements in this vector
+	*/
 	uint size() const {return c.size();}
+
+	/**
+	* @brief Returns self resized vector
+	*
+	* @param size new vector dimension
+	* @param new_value value with which the vector is filled
+	* @return resized vector
+	*/
 	_CVector & resize(uint size, const Type & new_value = Type()) {c.resize(size, new_value); return *this;}
+
+	/**
+	* @brief Returns copy of resized vector
+	*
+	* @param size new vector dimension
+	* @param new_value value with which the vector is filled
+	* @return resized vector
+	*/
 	_CVector resized(uint size, const Type & new_value = Type()) {_CVector tv = _CVector(*this); tv.resize(size, new_value); return tv;}
+
+	/**
+	* @brief Method that fills a vector with a value
+	*
+	* @param v value of which the vector is filled
+	* @return vector of type PIMathVector filled with "v"
+	*/
 	_CVector & fill(const Type & v) {PIMV_FOR(i, 0) c[i] = v; return *this;}
+
+	/**
+	* @brief Method that fills a vector with the adittion of vector value and "v"
+	*
+	* @param v value of which the vector is filled
+	* @return vector of type PIMathVector with values adittion of vector value and "v"
+	*/
 	_CVector & move(const Type & v) {PIMV_FOR(i, 0) c[i] += v; return *this;}
+
+	/**
+	* @brief Method that fills a vector with the adittion of vector value and "v"
+	*
+	* @param v vector of type PIMathVectorT
+	* @return vector of type PIMathVectorT with values adittion of vector value and "v"
+	*/
 	_CVector & move(const _CVector & v) {PIMV_FOR(i, 0) c[i] += v[i]; return *this;}
+
+	/**
+	* @brief Method that replaces two elements in a vector by indices. You cannot use an index larger than the number vector dimension,
+	*  otherwise there will be "undefined behavior"
+	*
+	* @param fe index of the first element
+	* @param se index of the second element
+	* @return resulting vector of type PIMathVector
+	*/
 	_CVector & swap(uint fe, uint se) {piSwap<Type>(c[fe], c[se]); return *this;}
+
+	/**
+	* @brief Method that returns sum of the squares of all elements of the vector
+	*
+	* @return value equal to the sum of the squares of all elements of the vector
+	*/
 	Type lengthSqr() const {Type tv(0); PIMV_FOR(i, 0) tv += (c[i] * c[i]); return tv;}
+
+	/**
+	* @brief Method that returns length of a vector
+	*
+	* @return value equal to length of a vector
+	*/
 	Type length() const {return sqrt(lengthSqr());}
+
+	/**
+	* @brief Method that returns the sum of the absolute values ​​of all vector values
+	*
+	* @return value equal sum of the absolute values ​​of all vector values
+	*/
 	Type manhattanLength() const {Type tv(0); PIMV_FOR(i, 0) tv += fabs(c[i]); return tv;}
+
+	/**
+	* @brief Method that returns the cos of the current vector and vector "v"
+	*
+	* @param v vector of type PIMathVector
+	* @return cos value of the angle between two vectors
+	*/
 	Type angleCos(const _CVector & v) const {Type tv = v.length() * length(); return (tv == Type(0) ? Type(0) : ((*this) ^ v) / tv);}
+
+	/**
+	* @brief Method that returns the sin of the current vector and vector "v". Works only with vectors which consists of 3 elements
+	*
+	* @param v vector of type PIMathVector
+	* @return sin value of the angle between two vector
+	*/
 	Type angleSin(const _CVector & v) const {Type tv = angleCos(v); return sqrt(Type(1) - tv * tv);}
+
+	/**
+	* @brief Method that returns the angle between of the current vector and vector "v" in Rad
+	*
+	* @param v vector of type PIMathVector
+	* @return value of the angle between two vectors in Rad
+	*/
 	Type angleRad(const _CVector & v) const {return acos(angleCos(v));}
+
+	/**
+	* @brief Method that returns the angle between of the current vector and vector "v" in Deg
+	*
+	* @param v vector of type PIMathVectorT
+	* @return value of the angle between two vectors in Deg
+	*/
 	Type angleDeg(const _CVector & v) const {return toDeg(acos(angleCos(v)));}
+
+	/**
+	* @brief Method that returns a vector equal to the projection of the current vector onto the vector "v"
+	*
+	* @param v vector of type PIMathVector
+	* @return vector of type PIMathVector equal to the projection of the current vector onto the vector "v"
+	*/
 	_CVector projection(const _CVector & v) {Type tv = v.length(); return (tv == Type(0) ? _CVector() : v * (((*this) ^ v) / tv));}
+
+	/**
+	* @brief Method that returns a normalized vector
+	*
+	* @return copy of normalized vector of type PIMathVector
+	*/
 	_CVector & normalize() {Type tv = length(); if (tv == Type(1)) return *this; if (piAbs<Type>(tv) <= Type(1E-100)) {fill(Type(0)); return *this;} PIMV_FOR(i, 0) c[i] /= tv; return *this;}
+
+	/**
+	* @brief Method that returns a normalized vector
+	*
+	* @return normalized vector of type PIMathVector
+	*/
 	_CVector normalized() {_CVector tv(*this); tv.normalize(); return tv;}
+
+	/**
+	* @brief Method which checks if every elements of vector are zeros
+	*
+	* @return true if vector is zero, else false
+	*/
 	bool isNull() const {PIMV_FOR(i, 0) if (c[i] != Type(0)) return false; return true;}
+
+	/**
+	* @brief Method which checks if vector is valid
+	*
+	* @return true if vector is valid, else false
+	*/
 	bool isValid() const {return !c.isEmpty();}
 
+	/**
+	* @brief Method which checks if current vector is orthogonal to vector "v"
+	*
+	* @param v vector of type PIMathVector
+	* @return true if vectors are orthogonal, else false
+	*/
 	bool isOrtho(const _CVector & v) const {return ((*this) ^ v) == Type(0);}
 
-    const Type & at(uint index) {return c[index];}
+	/**
+	* @brief Read-only access to elements reference by index of the vector element "index"
+	* If you enter an index out of the border of the vector there will be "undefined behavior"
+	*
+	* @param index is a parameter that shows the index number of the vector of the selected element
+	* @return reference to element of vector by index
+	*/
+	const Type & at(uint index) {return c[index];}
+
+	/**
+	* @brief Full access to the element of vector by index. If you enter an index out of the border of the vector there will be "undefined behavior"
+	*
+	* @param index is the index of necessary element
+	* @return element of vector
+	*/
 	Type & operator [](uint index) {return c[index];}
+
+	/**
+	* @brief Read-only access to the element of vector by index. If you enter an index out of the border of the vector there will be "undefined behavior"
+	*
+	* @param index is the index of necessary element
+	* @return element of vector
+	*/
 	Type operator [](uint index) const {return c[index];}
+
+	/**
+	* @brief Vector assignment to vector "v" of type PIMathVector
+	*
+	* @param v vector for the assigment
+	* @return vector equal to vector "v"
+	*/
 	_CVector & operator =(const _CVector & v) {c = v.c; return *this;}
+
+	/**
+	* @brief Vector assignment to value "v"
+	*
+	* @param v value for the assigment
+	* @return vector, each element of which is equal to the value "v"
+	*/
 	_CVector & operator =(const Type & v) {PIMV_FOR(i, 0) c[i] = v; return *this;}
+
+	/**
+	* @brief Compare with vector "v"
+	*
+	* @param v vector for the compare
+	* @return if vectors are equal true, else false
+	*/
 	bool operator ==(const _CVector & v) const {PIMV_FOR(i, 0) if (c[i] != v[i]) return false; return true;}
+
+	/**
+	* @brief Compare with vector "v"
+	*
+	* @param v vector for the compare
+	* @return if vectors are not equal true, else false
+	*/
 	bool operator !=(const _CVector & v) const {return !(*this == v);}
+
+	/**
+	* @brief Addition assignment with vector "v"
+	*
+	* @param v vector for the addition assigment
+	*/
 	void operator +=(const _CVector & v) {PIMV_FOR(i, 0) c[i] += v[i];}
+
+	/**
+	* @brief Subtraction assignment with vector "v"
+	*
+	* @param v vector for the subtraction assigment
+	*/
 	void operator -=(const _CVector & v) {PIMV_FOR(i, 0) c[i] -= v[i];}
+
+	/**
+	* @brief Multiplication assignment with value "v"
+	*
+	* @param v value for the multiplication assigment
+	*/
 	void operator *=(const Type & v) {PIMV_FOR(i, 0) c[i] *= v;}
+
+	/**
+	* @brief Multiplication assignment with vector "v"
+	*
+	* @param v vector for the multiplication assigment
+	*/
 	void operator *=(const _CVector & v) {PIMV_FOR(i, 0) c[i] *= v[i];}
+
+	/**
+	* @brief Division assignment with value "v"
+	*
+	* @param v value for the division assigment
+	*/
 	void operator /=(const Type & v) {PIMV_FOR(i, 0) c[i] /= v;}
+
+	/**
+	* @brief Division assignment with vector "v"
+	*
+	* @param v vector for the division assigment
+	*/
 	void operator /=(const _CVector & v) {PIMV_FOR(i, 0) c[i] /= v[i];}
+
+	/**
+	* @brief Vector substraction
+	*
+	* @return the result of vector substraction
+	*/
 	_CVector operator -() const {_CVector tv; PIMV_FOR(i, 0) tv[i] = -c[i]; return tv;}
+
+	/**
+	* @brief Matrix addition
+	*
+	* @param sm is matrix term
+	* @return the result of matrix addition
+	*/
 	_CVector operator +(const _CVector & v) const {_CVector tv = _CVector(*this); PIMV_FOR(i, 0) tv[i] += v[i]; return tv;}
+
+	/**
+	* @brief Vector substraction
+	*
+	* @return the result of vector substraction
+	*/
 	_CVector operator -(const _CVector & v) const {_CVector tv = _CVector(*this); PIMV_FOR(i, 0) tv[i] -= v[i]; return tv;}
+
+	/**
+	* @brief Vector multiplication with value "v"
+	*
+	* @param v is value factor
+	* @return the result of vector multiplication
+	*/
 	_CVector operator *(const Type & v) const {_CVector tv = _CVector(*this); PIMV_FOR(i, 0) tv[i] *= v; return tv;}
+
+	/**
+	* @brief Vector division with value "v"
+	*
+	* @param v is value divider
+	* @return the result of vector division
+	*/
 	_CVector operator /(const Type & v) const {_CVector tv = _CVector(*this); PIMV_FOR(i, 0) tv[i] /= v; return tv;}
+
+	/**
+	* @brief Cross product of two vectors. Works only with vector containing three elements, otherwise returns current vector
+	*
+	* @param v is vector for cross product
+	* @return the result vector equal of cross product
+	*/
 	_CVector operator *(const _CVector & v) const {if ((c.size() != 3) && (v.size() != 3)) return _CVector(); _CVector tv(3); tv.fill(Type(1)); tv[0] = c[1]*v[2] - v[1]*c[2]; tv[1] = v[0]*c[2] - c[0]*v[2]; tv[2] = c[0]*v[1] - v[0]*c[1]; return tv;}
+
+	/**
+	* @brief Elementwise assignment of multiplication of two vectors
+	*
+	* @param v is vector for multiplication
+	* @return resulting vector
+	*/
 	_CVector operator &(const _CVector & v) const {_CVector tv = _CVector(*this); PIMV_FOR(i, 0) tv[i] *= v[i]; return tv;}
+
+	/**
+	* @brief Absolute value of the dot product
+	*
+	* @param v is vector for dot product
+	* @return resulting vector
+	*/
 	Type operator ^(const _CVector & v) const {Type tv(0); PIMV_FOR(i, 0) tv += c[i] * v[i]; return tv;}
 
+	/**
+	* @brief Returns the distance between two vectors. Works only for 2-element vectors
+	*
+	* @param lp0 is vector
+	* @param lp1 is vector
+	* @return resulting value
+	*/
 	Type distToLine(const _CVector & lp0, const _CVector & lp1) {
 		_CVector a(lp0, lp1), b(lp0, *this), c(lp1, *this);
 		Type f = fabs(a[0]*b[1] - a[1]*b[0]) / a.length();
 		return f;
 	}
 
+	/**
+	* @brief Converts PIMathVector to PIVector type
+	*
+	* @return vector equal PIMathVector but in PIVector type
+	*/
 	PIVector<Type> toVector() const {return c;}
 
+	/**
+	* @brief Returns full access data of vector
+	*
+	* @return data of vector
+	*/
 	inline Type * data() {return c.data();}
+
+	/**
+	* @brief Returns read-only data of vector
+	*
+	* @return data of vector
+	*/
 	inline const Type * data() const {return c.data();}
 
 private:
@@ -555,11 +954,33 @@ template<typename Type>
 inline std::ostream & operator <<(std::ostream & s, const PIMathVector<Type> & v) {s << "{"; for (uint i = 0; i < v.size(); ++i) {s << v[i]; if (i < v.size() - 1) s << ", ";} s << "}"; return s;}
 #endif
 
+/**
+* @brief Inline operator for outputting the vector to the console
+*
+* @param s PICout type
+* @param the vector type PIMathVector that we print to the console
+* @return PIMathVector printed to the console
+*/
 template<typename Type>
 inline PICout operator <<(PICout s, const PIMathVector<Type> & v) {s << "Vector{"; for (uint i = 0; i < v.size(); ++i) {s << v[i]; if (i < v.size() - 1) s << ", ";} s << "}"; return s;}
 
+/**
+* @brief Inline operator for serializing a vector into a PIByteArray
+*
+* @param s PIByteArray type
+* @param v PIMathVector type
+* @return PIBiteArray serialized PIMathVector
+*/
 template<typename Type>
 inline PIByteArray & operator <<(PIByteArray & s, const PIMathVector<Type> & v) {s << v.c; return s;}
+
+/**
+* @brief Inline operator to deserialize vector from PIByteArray
+*
+* @param s PIByteArray type
+* @param v PIMathVector type
+* @return PIMathVector deserialized from PIByteArray
+*/
 template<typename Type>
 inline PIByteArray & operator >>(PIByteArray & s, PIMathVector<Type> & v) {s >> v.c; return s;}