From 42bfe7c587948b758cb02d792a084167795214aa Mon Sep 17 00:00:00 2001
From: Andrey <a.bychkov@itelma.su>
Date: Wed, 13 Apr 2022 14:02:31 +0300
Subject: [PATCH] PIVector doc

---
 libs/main/containers/pivector.h | 151 +++++++++++++++++++++++++++++---
 1 file changed, 141 insertions(+), 10 deletions(-)

diff --git a/libs/main/containers/pivector.h b/libs/main/containers/pivector.h
index 2e436891..7704fbf3 100644
--- a/libs/main/containers/pivector.h
+++ b/libs/main/containers/pivector.h
@@ -1367,11 +1367,9 @@ public:
 	}
 
 	//! \brief
-	//! \~english Remove no more than one element equal "v" and return reference to vector
-	//! \~russian
-	//! \details
-	//! \~english
-	//! \~russian
+	//! \~english Remove no more than one element equal `e`.
+	//! \~russian Удаляет первый элемент, который равен элементу `e`.
+	//! \~\details
 	//! \~\code
 	//! PIVector<int> v{3, 2, 5, 2, 7};
 	//! v.removeOne(2);
@@ -1389,11 +1387,9 @@ public:
 	}
 
 	//! \brief
-	//! \~english Remove no more than one element equal "v" and return reference to vector
-	//! \~russian
-	//! \details
-	//! \~english
-	//! \~russian
+	//! \~english Remove all elements equal `e`.
+	//! \~russian Удаляет все элементы, равные элементу `e`.
+	//! \~\details
 	//! \~\code
 	//! PIVector<int> v{3, 2, 5, 2, 7};
 	//! v.removeAll(2);
@@ -1410,6 +1406,18 @@ public:
 		return *this;
 	}
 
+	//! \brief
+	//! \~english Remove all elements in the array
+	//! passes the test implemented by the provided function `test`.
+	//! \~russian Удаляет все элементы, удовлетворяющие условию,
+	//! заданному в передаваемой функции `test`.
+	//! \~\details
+	//! \~\code
+	//! PIVector<int> v{3, 2, 5, 2, 7};
+	//! v.removeWhere([](const int & i){return i > 2;});
+	//! piCout << v; // 2, 2
+	//! \endcode
+	//! \~\sa \a remove(), \a removeOne(), \a removeWhere()
 	inline PIVector<T> & removeWhere(std::function<bool(const T & e)> test) {
 		for (ssize_t i = 0; i < size_s(); ++i) {
 			if (test(piv_data[i])) {
@@ -1420,6 +1428,25 @@ public:
 		return *this;
 	}
 
+	//! \brief
+	//! \~english Appends the given element `e` to the end of the array.
+	//! \~russian Добавляет элемент `e` в конец массива.
+	//! \~\details
+	//! \~english If the new size() is greater than capacity()
+	//! then all iterators and references
+	//! (including the past-the-end iterator) are invalidated.
+	//! Otherwise only the past-the-end iterator is invalidated.
+	//! \~russian Если новый size() больше, чем capacity(),
+	//! то все итераторы и указатели становятся нерабочими.
+	//! В противном случае, все, кроме итераторов указывающих на конец массива,
+	//! остаются в рабочем состоянии.
+	//! \~\code
+	//! PIVector<int> v{1, 2, 3};
+	//! v.push_back(4);
+	//! v.push_back(5);
+	//! piCout << v; // 1, 2, 3, 4, 5
+	//! \endcode
+	//! \~\sa \a push_front(), \a append(), \a prepend(), \a insert()
 	inline PIVector<T> & push_back(const T & e) {
 		alloc(piv_size + 1);
 		PIINTROSPECTION_CONTAINER_USED(T, 1);
@@ -1427,6 +1454,13 @@ public:
 		return *this;
 	}
 
+	//! \brief
+	//! \~english Appends the given element `e` to the end of the array.
+	//! \~russian Добавляет элемент `e` в конец массива.
+	//! \~\details
+	//! \~english Overloaded function.
+	//! \~russian Перегруженая функция.
+	//! \~\sa \a push_back()
 	inline PIVector<T> & push_back(T && e) {
 		alloc(piv_size + 1);
 		PIINTROSPECTION_CONTAINER_USED(T, 1);
@@ -1434,6 +1468,17 @@ public:
 		return *this;
 	}
 
+	//! \brief
+	//! \~english Appends the given elements to the end of the array.
+	//! \~russian Добавляет элементы в конец массива.
+	//! \~\details
+	//! \~english Overloaded function.
+	//! Appends the given elements from
+	//! [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).
+	//! \~\sa \a push_back()
 	inline PIVector<T> & push_back(std::initializer_list<T> init_list) {
 		size_t ps = piv_size;
 		alloc(piv_size + init_list.size());
@@ -1441,6 +1486,13 @@ public:
 		return *this;
 	}
 
+	//! \brief
+	//! \~english Appends the given array `v` to the end of the array.
+	//! \~russian Добавляет массив `v` в конец массива.
+	//! \~\details
+	//! \~english Overloaded function.
+	//! \~russian Перегруженая функция.
+	//! \~\sa \a push_back()
 	inline PIVector<T> & push_back(const PIVector<T> & v) {
 #ifdef PIP_DEBUG
 		if (&v == this) {
@@ -1454,13 +1506,92 @@ public:
 		return *this;
 	}
 
+	//! \brief
+	//! \~english Appends the given element `e` to the end of the array.
+	//! \~russian Добавляет элемент `e` в конец массива.
+	//! \~\details
+	//! \~english If the new size() is greater than capacity()
+	//! then all iterators and references
+	//! (including the past-the-end iterator) are invalidated.
+	//! Otherwise only the past-the-end iterator is invalidated.
+	//! \~russian Если новый size() больше, чем capacity(),
+	//! то все итераторы и указатели становятся нерабочими.
+	//! В противном случае, все, кроме итераторов указывающих на конец массива,
+	//! остаются в рабочем состоянии.
+	//! \~\code
+	//! PIVector<int> v{1, 2, 3};
+	//! v.append(4);
+	//! v.append(5);
+	//! piCout << v; // 1, 2, 3, 4, 5
+	//! \endcode
+	//! \~\sa \a prepend(), \a push_front(), \a push_back(), \a insert()
 	inline PIVector<T> & append(const T & e) {return push_back(e);}
+
+	//! \brief
+	//! \~english Appends the given element `e` to the end of the array.
+	//! \~russian Добавляет элемент `e` в конец массива.
+	//! \~\details
+	//! \~english Overloaded function.
+	//! \~russian Перегруженая функция.
+	//! \~\sa \a append()
 	inline PIVector<T> & append(T && e) {return push_back(std::move(e));}
+
+	//! \brief
+	//! \~english Appends the given elements to the end of the array.
+	//! \~russian Добавляет элементы в конец массива.
+	//! \~\details
+	//! \~english Overloaded function.
+	//! Appends the given elements from
+	//! [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).
+	//! \~\sa \a append()
 	inline PIVector<T> & append(std::initializer_list<T> init_list) {return push_back(init_list);}
+
+	//! \brief
+	//! \~english Appends the given array `v` to the end of the array.
+	//! \~russian Добавляет массив `v` в конец массива.
+	//! \~\details
+	//! \~english Overloaded function.
+	//! \~russian Перегруженая функция.
+	//! \~\sa \a append()
 	inline PIVector<T> & append(const PIVector<T> & v) {return push_back(v);}
 
+	//! \brief
+	//! \~english Appends the given element `e` to the end of the array.
+	//! \~russian Добавляет элемент `e` в конец массива.
+	//! \~\details
+	//! \~\code
+	//! PIVector<int> v{1, 2, 3};
+	//! v << 4 << 5;
+	//! piCout << v; // 1, 2, 3, 4, 5
+	//! \endcode
+	//! \~\sa \a append()
 	inline PIVector<T> & operator <<(const T & e) {return push_back(e);}
+
+	//! \brief
+	//! \~english Appends the given element `e` to the end of the array.
+	//! \~russian Добавляет элемент `e` в конец массива.
+	//! \~\details
+	//! \~\code
+	//! PIVector<int> v{1, 2, 3};
+	//! v << 4 << 5;
+	//! piCout << v; // 1, 2, 3, 4, 5
+	//! \endcode
+	//! \~\sa \a append()
 	inline PIVector<T> & operator <<(T && e) {return push_back(std::move(e));}
+
+	//! \brief
+	//! \~english Appends the given array `v` to the end of the array.
+	//! \~russian Добавляет массив `v` в конец массива.
+	//! \~\details
+	//! \~\code
+	//! PIVector<int> v{1, 2, 3};
+	//! v << PIVector<int>{4, 5};
+	//! piCout << v; // 1, 2, 3, 4, 5
+	//! \endcode
+	//! \~\sa \a append()
 	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;}