From 7a9c3f72ca74fe0ea8334354900d5b7ec4047006 Mon Sep 17 00:00:00 2001
From: Andrey <a.bychkov@itelma.su>
Date: Mon, 28 Mar 2022 17:59:09 +0300
Subject: [PATCH] PIVector doc

---
 libs/main/containers/pivector.h | 93 +++++++++++++++++++++++++++++----
 1 file changed, 82 insertions(+), 11 deletions(-)

diff --git a/libs/main/containers/pivector.h b/libs/main/containers/pivector.h
index e8314dd8..383158fa 100644
--- a/libs/main/containers/pivector.h
+++ b/libs/main/containers/pivector.h
@@ -95,39 +95,88 @@
 template <typename T>
 class PIVector {
 public:
-	//! Contructs an empty vector
+
+	//! \~\brief
+	//! \~english Constructs an empty vector
+	//! \~russian Создает пустой массив
 	inline PIVector(): piv_data(0), piv_size(0), piv_rsize(0) {
 		PIINTROSPECTION_CONTAINER_NEW(T, sizeof(T))
 	}
-	//! \brief Contructs vector with size "size" filled elements "value"
+
+	//! \~\brief
+	//! \~english Contructs vector from raw `data`.
+	//! This constructor reserve `size` and copy from `data` pointer.
+	//! \~russian Создает массив из указателя на данные `data` и размер `size`.
+	//! То есть выделяет память для `size` элементов и копирует данные из указателя `data`.
 	inline PIVector(const T * data, size_t size): piv_data(0), piv_size(0), piv_rsize(0) {
 		PIINTROSPECTION_CONTAINER_NEW(T, sizeof(T))
 		alloc(size);
 		newT(piv_data, data, piv_size);
 	}
+
+	//! \~\brief
+	//! \~english Copy constructor
+	//! \~russian Копирующий конструктор
 	inline PIVector(const PIVector<T> & v): piv_data(0), piv_size(0), piv_rsize(0) {
 		PIINTROSPECTION_CONTAINER_NEW(T, sizeof(T))
 		alloc(v.piv_size);
 		newT(piv_data, v.piv_data, piv_size);
 	}
-	//! \brief Contructs vector from C++11 initializer list
+
+	//! \~\brief
+	//! \~english Contructs vector from C++11 initializer list.
+	//! \~russian Создает массив из списка инициализации C++11.
+	//! \~\details
+	//! \~english
+	//! [C++11 initializer list](https://en.cppreference.com/w/cpp/utility/initializer_list).
+	//! \~russian
+	//! [Список инициализации C++11](https://ru.cppreference.com/w/cpp/utility/initializer_list).
+	//! \~\code
+	//!	PIVector <int> v{1,2,3};
+	//! piCout << v;
+	//! // {1, 2, 3}
+	//! \endcode
 	inline PIVector(std::initializer_list<T> init_list): piv_data(0), piv_size(0), piv_rsize(0) {
 		PIINTROSPECTION_CONTAINER_NEW(T, sizeof(T))
 		alloc(init_list.size());
 		newT(piv_data, init_list.begin(), init_list.size());
 	}
-	inline PIVector(size_t piv_size, const T & f = T()): piv_data(0), piv_size(0), piv_rsize(0) {
+
+	//! \~\brief
+	//! \~english Contructs vector with size `size` filled elements `e`.
+	//! \~russian Создает массив из `size` элементов заполненных `e`.
+	inline PIVector(size_t size, const T & e = T()): piv_data(0), piv_size(0), piv_rsize(0) {
 		PIINTROSPECTION_CONTAINER_NEW(T, sizeof(T))
-		resize(piv_size, f);
+		resize(size, e);
 	}
-	inline PIVector(size_t piv_size, std::function<T(size_t i)> f): piv_data(0), piv_size(0), piv_rsize(0) {
+
+	//! \~\brief
+	//! \~english Contructs vector with size `size` and elements created by function `f(size_t i)`.
+	//! \~russian Создает массив из `size` элементов созданных функцией `f(size_t i)`.
+	//! \~\details
+	//! \~english Can use [Lambda expressions](https://en.cppreference.com/w/cpp/language/lambda) as constructor argument.
+	//! \~russian Позволяет передавать [Лямбда-выражения](https://ru.cppreference.com/w/cpp/language/lambda) для создания элементов в конструкторе.
+	//! \~\code
+	//!	PIVector <int> v(5, [](size_t i){return i*2;});
+	//! piCout << v;
+	//! // {0, 2, 4, 6, 8}
+	//! \endcode
+	inline PIVector(size_t size, std::function<T(size_t i)> f): piv_data(0), piv_size(0), piv_rsize(0) {
 		PIINTROSPECTION_CONTAINER_NEW(T, sizeof(T))
-		resize(piv_size, f);
+		resize(size, f);
 	}
+
+	//! \~\brief
+	//! \~english Move constructor
+	//! \~russian Перемещающий конструктор
 	inline PIVector(PIVector<T> && v): piv_data(v.piv_data), piv_size(v.piv_size), piv_rsize(v.piv_rsize) {
 		PIINTROSPECTION_CONTAINER_NEW(T, sizeof(T))
 		v._reset();
 	}
+
+	//! \~\brief
+	//! \~english Destructor
+	//! \~russian Деструктор
 	inline virtual ~PIVector() {
 		PIINTROSPECTION_CONTAINER_DELETE(T)
 		PIINTROSPECTION_CONTAINER_FREE(T, (piv_rsize))
@@ -136,6 +185,9 @@ public:
 		_reset();
 	}
 
+	//! \~\brief
+	//! \~english Assign operator
+	//! \~russian Оператор присваивания
 	inline PIVector<T> & operator =(const PIVector<T> & v) {
 		if (this == &v) return *this;
 		clear();
@@ -145,11 +197,17 @@ public:
 		return *this;
 	}
 
+	//! \~\brief
+	//! \~english Assign move operator
+	//! \~russian Оператор перемещающего присваивания
 	inline PIVector<T> & operator =(PIVector<T> && v) {
 		swap(v);
 		return *this;
 	}
 
+	//! \~\brief
+	//! \~english Reshape order enum for \a reshape function.
+	//! \~russian Порядок обхода для функции изменения размерности \a reshape.
 	enum ReshapeOrder {
 		byRow,
 		byColumn
@@ -574,23 +632,36 @@ public:
 		return *this;
 	}
 
-	inline PIVector<T> & append(const T & e) {return push_back(e);}
-	inline PIVector<T> & append(T && e) {return push_back(std::move(e));}
-	inline PIVector<T> & append(const PIVector<T> & v) {
+	inline PIVector<T> & push_back(std::initializer_list<T> init_list) {
+		size_t ps = piv_size;
+		alloc(piv_size + init_list.size());
+		newT(piv_data + ps, init_list.begin(), init_list.size());
+		return *this;
+	}
+
+	inline PIVector<T> & push_back(const PIVector<T> & v) {
 		assert(&v != this);
 		size_t ps = piv_size;
 		alloc(piv_size + v.piv_size);
 		newT(piv_data + ps, v.piv_data, v.piv_size);
 		return *this;
 	}
+
+	inline PIVector<T> & append(const T & e) {return push_back(e);}
+	inline PIVector<T> & append(T && e) {return push_back(std::move(e));}
+	inline PIVector<T> & append(std::initializer_list<T> init_list) {return push_back(init_list);}
+	inline PIVector<T> & append(const PIVector<T> & v) {return push_back(v);}
+
 	inline PIVector<T> & operator <<(const T & e) {return push_back(e);}
 	inline PIVector<T> & operator <<(T && e) {return push_back(std::move(e));}
-	inline PIVector<T> & operator <<(const PIVector<T> & v) {return append(v);}
+	inline PIVector<T> & operator <<(const PIVector<T> & v) {return push_back(v);}
 
 	inline PIVector<T> & push_front(const T & e) {insert(0, e); return *this;}
 	inline PIVector<T> & push_front(T && e) {insert(0, std::move(e)); return *this;}
+	inline PIVector<T> & push_front(const PIVector<T> & v) {insert(0, v); return *this;}
 	inline PIVector<T> & prepend(const T & e) {return push_front(e);}
 	inline PIVector<T> & prepend(T && e) {return push_front(std::move(e));}
+	inline PIVector<T> & prepend(const PIVector<T> & v) {return push_front(v);}
 
 	inline PIVector<T> & pop_back() {
 		if (piv_size == 0) return *this;