merged AI doc, some new pages

libs/main/math/pimathmatrix.h

@@ -1,5 +1,5 @@
-//! \file pimathmatrix.h
-//! \ingroup Math
+//! \~\file pimathmatrix.h
+//! \~\ingroup Math
 //! \~\brief
 //! \~english Math matrix
 //! \~russian Математическая матрица
@@ -32,31 +32,34 @@
 
 /// Matrix templated
 
-#define PIMM_FOR                    \
-	for (uint r = 0; r < Rows; ++r) \
-		for (uint c = 0; c < Cols; ++c)
+#define PIMM_FOR                  \
+  for (uint r = 0; r < Rows; ++r) \
+	for (uint c = 0; c < Cols; ++c)
 #define PIMM_FOR_C for (uint i = 0; i < Cols; ++i)
 #define PIMM_FOR_R for (uint i = 0; i < Rows; ++i)
 
 #pragma pack(push, 1)
 
+//! \~\ingroup Math
+//! \~\brief
 //! \~english
+//! Fixed-size math matrix. Stores matrix data inline and performs dimension checks at compile time where possible.
 //! \brief A class for fixed size and type matrix.
 //! \tparam `Rows` rows number of matrix.
 //! \tparam `Сols` columns number of matrix.
 //! \tparam `Type` is the data type of the matrix. There are can be basic C++ language data and different classes where the arithmetic
-//! operators(=, +=, -=, *=, /=, ==, !=, +, -, *, /)
-//!  of the C++ language are implemented
+//! operators(=, +=, -=, *=, /=, ==, !=, +, -, *, /) of the C++ language are implemented
 //! \~russian
+//! Математическая матрица фиксированного размера. Хранит данные матрицы внутри объекта и по возможности проверяет размерности на этапе
+//! компиляции.
 //! \brief Класс для работы с матрицами фиксированного размера и типа данных.
-//! \details В отличие от \a PIMathMatrix не занимается динамическим выделением памяти и связанными с этим операциями.
-//! То есть он тривиально копируемый.
-//! Содержит проверки времени компиляции на несоответствие размера при различных математических операциях,
-//! что позволяет заранее выявлять ошибки.
+//! \details В отличие от \a PIMathMatrix не
+//! занимается динамическим выделением памяти и связанными с этим операциями. То есть он тривиально копируемый. Содержит проверки времени
+//! компиляции на несоответствие размера при различных математических операциях, что позволяет заранее выявлять ошибки.
 //! \tparam `Rows` количество строк матрицы.
 //! \tparam `Сols` количество столбцов матрицы.
-//! \tparam `Type`тип данных матрицы. Здесь можеть быть базовый тип данных C++ или различные классы,
-//! где реализованы арифметические операторы(=, +=, -=, *=, /=, ==, !=, +, -, *, /) языка C++.
+//! \tparam `Type`тип данных матрицы. Здесь можеть быть базовый тип
+//! данных C++ или различные классы, где реализованы арифметические операторы(=, +=, -=, *=, /=, ==, !=, +, -, *, /) языка C++.
 template<uint Rows, uint Cols = Rows, typename Type = double>
 class PIP_EXPORT PIMathMatrixT {
 	typedef PIMathMatrixT<Rows, Cols, Type> _CMatrix;
@@ -148,6 +151,7 @@ public:
 	//! \details Если вы введете индекс вне границ матрицы, то поведение не определено ("undefined behavior").
 	//! \param index номер выбранной строки.
 	//! \return строка в формате \a PIMathVectorT.
+	//! \sa col()
 	PIMathVectorT<Cols, Type> row(uint index) {
 		PIMathVectorT<Cols, Type> tv;
 		PIMM_FOR_C tv[i] = m[index][i];
@@ -200,6 +204,7 @@ public:
 	//! \param rf номер первой выбранной строки.
 	//! \param rs номер второй выбранной строки.
 	//! \return матрица типа \a PIMathMatrixT<Rows, Cols, Type>.
+	//! \sa swapCols()
 	PIMathMatrixT<Rows, Cols, Type> & swapRows(uint rf, uint rs) {
 		PIMM_FOR_C piSwap<Type>(m[rf][i], m[rs][i]);
 		return *this;
@@ -214,9 +219,10 @@ public:
 	//! \~russian
 	//! \brief Метод, меняющий местами выбранные столбцы в матрице.
 	//! \details Если вы введете индекс вне границ матрицы, то поведение не определено ("undefined behavior").
-	//! \param rf номер первого выбранного столбца.
-	//! \param rs номер второго выбранного столбца.
+	//! \param cf номер первого выбранного столбца.
+	//! \param cs номер второго выбранного столбца.
 	//! \return матрица типа \a PIMathMatrixT<Rows, Cols, Type>.
+	//! \sa swapRows()
 	PIMathMatrixT<Rows, Cols, Type> & swapCols(uint cf, uint cs) {
 		PIMM_FOR_R piSwap<Type>(m[i][cf], m[i][cs]);
 		return *this;
@@ -260,6 +266,7 @@ public:
 	//! \~russian
 	//! \brief Метод, являются ли все элементы матрицы нулями.
 	//! \return true если матрица нулевая, иначе false.
+	//! \sa isIdentity()
 	bool isNull() const {
 		PIMM_FOR if (m[r][c] != Type(0)) return false;
 		return true;
@@ -292,6 +299,7 @@ public:
 	//! \param row номер строки матрицы.
 	//! \param col номер столбца матрицы.
 	//! \return элемент матрицы.
+	//! \sa at(), element(uint, uint) const
 	inline Type & element(uint row, uint col) { return m[row][col]; }
 
 	//! \~english
@@ -306,6 +314,7 @@ public:
 	//! \param row номер строки матрицы.
 	//! \param col номер столбца матрицы.
 	//! \return копия элемента матрицы.
+	//! \sa at(), element(uint, uint)
 	inline const Type & element(uint row, uint col) const { return m[row][col]; }
 
 	//! \~english
@@ -873,11 +882,23 @@ inline PIMathMatrixT<Rows, Cols, Type> operator*(const Type & x, const PIMathMat
 }
 
 
+//! \~english 2 x 2 fixed-size matrix of \c int.
+//! \~russian Матрица 2 x 2 фиксированного размера из \c int.
 typedef PIMathMatrixT<2u, 2u, int> PIMathMatrixT22i;
+//! \~english 3 x 3 fixed-size matrix of \c int.
+//! \~russian Матрица 3 x 3 фиксированного размера из \c int.
 typedef PIMathMatrixT<3u, 3u, int> PIMathMatrixT33i;
+//! \~english 4 x 4 fixed-size matrix of \c int.
+//! \~russian Матрица 4 x 4 фиксированного размера из \c int.
 typedef PIMathMatrixT<4u, 4u, int> PIMathMatrixT44i;
+//! \~english 2 x 2 fixed-size matrix of \c double.
+//! \~russian Матрица 2 x 2 фиксированного размера из \c double.
 typedef PIMathMatrixT<2u, 2u, double> PIMathMatrixT22d;
+//! \~english 3 x 3 fixed-size matrix of \c double.
+//! \~russian Матрица 3 x 3 фиксированного размера из \c double.
 typedef PIMathMatrixT<3u, 3u, double> PIMathMatrixT33d;
+//! \~english 4 x 4 fixed-size matrix of \c double.
+//! \~russian Матрица 4 x 4 фиксированного размера из \c double.
 typedef PIMathMatrixT<4u, 4u, double> PIMathMatrixT44d;
 
 
@@ -891,21 +912,24 @@ class PIMathMatrix;
 
 /// Matrix
 
-#define PIMM_FOR                           \
-	for (uint r = 0; r < _V2D::rows_; ++r) \
-		for (uint c = 0; c < _V2D::cols_; ++c)
+#define PIMM_FOR                         \
+  for (uint r = 0; r < _V2D::rows_; ++r) \
+	for (uint c = 0; c < _V2D::cols_; ++c)
 #define PIMM_FOR_A for (uint i = 0; i < _V2D::mat.size(); ++i)
 #define PIMM_FOR_C for (uint i = 0; i < _V2D::cols_; ++i)
 #define PIMM_FOR_R for (uint i = 0; i < _V2D::rows_; ++i)
 
+//! \~\ingroup Math
+//! \~\brief
 //! \~english
+//! Dynamic-size math matrix. Uses \a PIVector2D as storage and keeps the matrix interface aligned with \a PIMathMatrixT.
 //! \brief A class for dynamic size and fixed type matrix.
 //! \tparam `Type` There are can be basic C++ language data and different classes where the arithmetic operators(=, +=, -=, *=, /=, ==, !=,
 //! +, -, *, /) of the C++ language are implemented.
 //! \~russian
-//! \brief Класс для работы с матрицами динамического размера и фиксированного типа.
-//! \tparam `Type` Здесь можеть быть базовый тип данных C++ или различные классы,
-//! где реализованы арифметические операторы(=, +=, -=, *=, /=, ==, !=, +, -, *, /) языка C++.
+//! Математическая матрица динамического размера. Использует \a PIVector2D как хранилище и сохраняет интерфейс, согласованный с \a
+//! PIMathMatrixT. \brief Класс для работы с матрицами динамического размера и фиксированного типа. \tparam `Type` Здесь можеть быть базовый
+//! тип данных C++ или различные классы, где реализованы арифметические операторы(=, +=, -=, *=, /=, ==, !=, +, -, *, /) языка C++.
 template<typename Type>
 class PIP_EXPORT PIMathMatrix: public PIVector2D<Type> {
 	typedef PIVector2D<Type> _V2D;
@@ -1113,6 +1137,7 @@ public:
 	//! \~russian
 	//! \brief Метод, проверяющий содержит ли главная диагональ единицы и все остальные поля нули.
 	//! \return true если матрица единичная, иначе false.
+	//! \sa isNull(), isValid()
 	bool isIdentity() const {
 		PIMM_FOR if ((c == r) ? _V2D::element(r, c) != Type(1) : _V2D::element(r, c) != Type(0)) return false;
 		return true;
@@ -1124,6 +1149,7 @@ public:
 	//! \~russian
 	//! \brief Метод, являются ли все элементы матрицы нулями.
 	//! \return true если матрица нулевая, иначе false.
+	//! \sa isIdentity()
 	bool isNull() const {
 		PIMM_FOR_A if (_V2D::mat[i] != Type(0)) return false;
 		return true;
@@ -1135,6 +1161,7 @@ public:
 	//! \~russian
 	//! \brief Метод, который проверяет является ли матрица пустой.
 	//! \return true если матрица действительна, иначе false.
+	//! \sa isNull(), isIdentity()
 	bool isValid() const { return !PIVector2D<Type>::isEmpty(); }
 
 	//! \~english
@@ -1607,17 +1634,15 @@ inline PIMathMatrix<Type> operator*(const Type & x, const PIMathMatrix<Type> & v
 	return v * x;
 }
 
+//! \~english Dynamic matrix of \c int.
+//! \~russian Динамическая матрица из \c int.
 typedef PIMathMatrix<int> PIMathMatrixi;
+//! \~english Dynamic matrix of \c double.
+//! \~russian Динамическая матрица из \c double.
 typedef PIMathMatrix<double> PIMathMatrixd;
 
-//! \~english
-//! \brief Searching hermitian matrix.
-//! \param m conjugate transpose matrix.
-//! \return result of the hermitian.
-//! \~russian
-//! \brief Поиск эрмитовой матрицы.
-//! \param m сопряженная транспонированная матрица.
-//! \return результат преобразования.
+//! \~english Returns the Hermitian form of complex matrix \a m.
+//! \~russian Возвращает эрмитову форму комплексной матрицы \a m.
 template<typename T>
 PIMathMatrix<complex<T>> hermitian(const PIMathMatrix<complex<T>> & m) {
 	PIMathMatrix<complex<T>> ret(m);