From 1edd9e4c55ae799890e41d4e03052880a388551f Mon Sep 17 00:00:00 2001
From: Andrey <a.bychkov@itelma.su>
Date: Thu, 31 Mar 2022 17:27:36 +0300
Subject: [PATCH] PIVector doc

---
 libs/main/containers/pivector.h | 53 +++++++++++++++++++++++++++++++--
 1 file changed, 50 insertions(+), 3 deletions(-)

diff --git a/libs/main/containers/pivector.h b/libs/main/containers/pivector.h
index 29fd5575..b68602a2 100644
--- a/libs/main/containers/pivector.h
+++ b/libs/main/containers/pivector.h
@@ -362,7 +362,10 @@ public:
 	//! \~\brief
 	//! \~english Number of elements that the container has currently allocated space for.
 	//! \~russian Количество элементов, для которого сейчас выделена память контейнером.
-	//! \~\sa \a size \a size_s, \a isEmpty, \a isNotEmpty, \a resize, \a reserve
+	//! \~\details
+	//! \~english To find out the actual number of items, use the function \a size().
+	//! \~russian Чтобы узнать фактическое количество элементов используйте функцию \a size().
+	//! \~\sa \a reserve, \a size \a size_s
 	inline size_t capacity() const {return piv_rsize;}
 
 	//! \~\brief
@@ -810,9 +813,13 @@ public:
 	//! \~english Read only pointer to array
 	//! \~russian Указатель на память массива только для чтения.
 	//! \~\details
-	//! \~english Optional argument `index` the position in this array,
+	//! \~english The pointer can be used to access and modify the items in the vector.
+	//! The pointer remains valid as long as the vector isn't reallocated.
+	//! Optional argument `index` the position in this array,
 	//! where is pointer. Default: start of array.
-	//! \~russian Опциональный аргумент `index` указывает на индекс c которого брать указатель.
+	//! \~russian Указатель можно использовать для доступа и изменения элементов в массиве.
+	//! Указатель остается действительным только до тех пор, пока массив не будет перераспределен.
+	//! Опциональный аргумент `index` указывает на индекс c которого брать указатель.
 	//! По умолчанию указывает на начало массива.
 	//! \~\code
 	//! PIVector<int> v{1, 3, 5};
@@ -932,6 +939,18 @@ public:
 		return fill(f);
 	}
 
+	//! \~\brief
+	//! \~english Sets size of the array, new elements are copied from `f`.
+	//! \~russian Устанавливает размер массива, новые элементы копируются из `f`.
+	//! \~\details
+	//! \~english If `new_size` is greater than the current \a size,
+	//!  elements are added to the end; the new elements are initialized from `f`.
+	//! If `new_size` is less than the current \a size, elements are removed from the end.
+	//! \~russian Если `new_size` больше чем текущий размер массива \a size,
+	//! новые элементы добавляются в конец массива и создаются из `f`.
+	//! Если `new_size` меньше чем текущий размер массива \a size,
+	//! лишние элементы удаляются с конца массива.
+	//! \~\sa \a size, \a clear
 	inline PIVector<T> & resize(size_t new_size, const T & f = T()) {
 		if (new_size < piv_size) {
 			T * de = &(piv_data[new_size]);
@@ -949,6 +968,18 @@ public:
 		return *this;
 	}
 
+	//! \~\brief
+	//! \~english Sets size of the array, new elements created by function `f(size_t i)`.
+	//! \~russian Устанавливает размер массива, новые элементы создаются функцией `f(size_t i)`.
+	//! \~\details
+	//! \~english If `new_size` is greater than the current \a size,
+	//!  elements are added to the end; the new elements created by function `f(size_t i)`.
+	//! If `new_size` is less than the current \a size, elements are removed from the end.
+	//! \~russian Если `new_size` больше чем текущий размер массива \a size,
+	//! новые элементы добавляются в конец массива и функцией `f(size_t i)`.
+	//! Если `new_size` меньше чем текущий размер массива \a size,
+	//! лишние элементы удаляются с конца массива.
+	//! \~\sa \a size, \a clear
 	inline PIVector<T> & resize(size_t new_size, std::function<T(size_t i)> f) {
 		if (new_size < piv_size) {
 			T * de = &(piv_data[new_size]);
@@ -979,10 +1010,26 @@ public:
 		alloc(new_size);
 		return *this;
 	}
+
 	inline void _copyRaw(T * dst, const T * src, size_t size) {
 		newT(dst, src, size);
 	}
 
+	//! \~\brief
+	//! \~english Attempts to allocate memory for at least `new_size` elements.
+	//! \~russian Резервируется память под как минимум `new_size` элементов.
+	//! \~\details
+	//! \~english  If you know in advance how large the array will be,
+	//! you should call this function to prevent reallocations and memory fragmentation.
+	//! If `new_size` is greater than the current \a capacity,
+	//! new storage is allocated, otherwise the function does nothing.
+	//! This function does not change the \a size of the array.
+	//! \~russian Если вы заранее знаете, насколько велик будет массив,
+	//! вы можете вызвать эту функцию, чтобы предотвратить перераспределение и фрагментацию памяти.
+	//! Если размер `new_size` больше чем выделенная память \a capacity,
+	//! то произойдёт выделение новой памяти и перераспределение массива.
+	//! Эта функция не изменяет количество элементов в массиве \a size.
+	//! \~\sa \a size, \a capacity, \a resize
 	inline PIVector<T> & reserve(size_t new_size) {
 		if (new_size <= piv_rsize) return *this;
 		size_t os = piv_size;