From f83d08cf567e4e603f6823d6bc7bba4d220c871a Mon Sep 17 00:00:00 2001
From: Andrey <a.bychkov@itelma.su>
Date: Fri, 1 Apr 2022 18:11:52 +0300
Subject: [PATCH] PIVector doc

---
 libs/main/containers/pivector.h | 46 ++++++++++++++++++++++++++++++++-
 1 file changed, 45 insertions(+), 1 deletion(-)

diff --git a/libs/main/containers/pivector.h b/libs/main/containers/pivector.h
index 6833dba2..83ec4659 100644
--- a/libs/main/containers/pivector.h
+++ b/libs/main/containers/pivector.h
@@ -1025,7 +1025,7 @@ public:
 	//! \~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,
+	//! \~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.
@@ -1044,6 +1044,18 @@ public:
 		return *this;
 	}
 
+	//! \~\brief
+	//! \~english Inserts value `e` at `index` position in the array.
+	//! \~russian Вставляет значение `e` в позицию `index` в массиве.
+	//! \~\details
+	//! \~english The index must be greater than 0 and less than or equal to \a size().
+	//! \~russian Индекс должен быть больше 0 и меньше или равен \a size().
+	//! \code
+	//! PIVector<int> v{1, 3, 5};
+	//! v.insert(2, 7);
+	//! piCout << v; // 1, 3, 7, 5
+	//! \endcode
+	//! \~\sa \a append(), \a prepend(), \a remove()
 	inline PIVector<T> & insert(size_t index, const T & e = T()) {
 		alloc(piv_size + 1);
 		if (index < piv_size - 1) {
@@ -1054,6 +1066,14 @@ public:
 		elementNew(piv_data + index, e);
 		return *this;
 	}
+
+	//! \~\brief
+	//! \~english Inserts value `e` at `index` position in the array.
+	//! \~russian Вставляет значение `e` в позицию `index` в массиве.
+	//! \~\details
+	//! \~english The index must be greater than 0 and less than or equal to \a size().
+	//! \~russian Индекс должен быть больше 0 и меньше или равен \a size().
+	//! \~\sa \a append(), \a prepend(), \a remove()
 	inline PIVector<T> & insert(size_t index, T && e) {
 		alloc(piv_size + 1);
 		if (index < piv_size - 1) {
@@ -1064,6 +1084,14 @@ public:
 		elementNew(piv_data + index, std::move(e));
 		return *this;
 	}
+
+	//! \~\brief
+	//! \~english Inserts array `v` at `index` position in the array.
+	//! \~russian Вставляет массив `v` в позицию `index` в массиве.
+	//! \~\details
+	//! \~english The index must be greater than or equal to 0 and less than or equal to \a size().
+	//! \~russian Индекс должен быть больше или равен 0 и меньше или равен \a size().
+	//! \~\sa \a append(), \a prepend(), \a remove()
 	inline PIVector<T> & insert(size_t index, const PIVector<T> & v) {
 		if (v.isEmpty()) return *this;
 		assert(&v != this);
@@ -1076,6 +1104,16 @@ public:
 		return *this;
 	}
 
+	//! \~\brief
+	//! \~english Removes `count` elements from the middle of the array, starting at `index` position.
+	//! \~russian Удаляет элементы из массива, начиная с позиции `index`, в количестве `count`.
+	//! \~\details
+	//! \code
+	//! PIVector<int> v{1, 3, 7, 5};
+	//! v.remove(1, 2);
+	//! piCout << v; // 1, 5
+	//! \endcode
+	//! \~\sa \a resize(), \a insert()
 	inline PIVector<T> & remove(size_t index, size_t count = 1) {
 		if (count == 0) return *this;
 		if (index + count >= piv_size) {
@@ -1089,6 +1127,12 @@ public:
 		return *this;
 	}
 
+	//! \~\brief
+	//! \~english Swaps array `v` other with this array.
+	//! \~russian Меняет местами массив `v` с этим массивом.
+	//! \~\details
+	//! \~english This operation is very fast and never fails.
+	//! \~russian Эта операция выполняется мгновенно без копирования памяти и никогда не дает сбоев.
 	inline void swap(PIVector<T> & v) {
 		piSwap<T*>(piv_data, v.piv_data);
 		piSwap<size_t>(piv_size, v.piv_size);