containers doc

libs/main/containers/pistack.h

@@ -1,8 +1,17 @@
-/*! \file pistack.h
- * \brief Stack container
- * 
- * This file declare PIStack
-*/
+//! \addtogroup Containers
+//! \{
+//! \file pistack.h
+//! \brief
+//! \~english Declares \a PIStack
+//! \~russian Объявление \a PIStack
+//! \~\authors
+//! \~english
+//! Ivan Pelipenko peri4ko@yandex.ru;
+//! Andrey Bychkov work.a.b@yandex.ru;
+//! \~russian
+//! Иван Пелипенко peri4ko@yandex.ru;
+//! Андрей Бычков work.a.b@yandex.ru;
+//! \~\}
 /*
 	PIP - Platform Independent Primitives
 	Stack container
@@ -28,16 +37,63 @@
 #include "pivector.h"
 #include "pideque.h"
 
+//! \addtogroup Containers
+//! \{
+//! \class PIStack
+//! \brief
+//! \~english A container class inherited from the \a PIVector with stack functionality.
+//! \~russian Класс контейнера наследованый от \a PIVector с функциональностью стека.
+//! \~\}
+//! \details
+//! \~english The container is a array of elements organized according to the LIFO principle (last in, first out).
+//! Adds \a push() and \pop() functions to \a PIVector.
+//! \~russian Контейнер представляющий массив элементов, организованных по принципу LIFO (последним пришёл — первым вышел).
+//! Добавляет к \a PIVector функции \a push() и \a pop().
+//! \~\sa \a PIVector
 template<typename T>
 class PIStack: public PIVector<T> {
 public:
+
+	//! \~english Constructs an empty array.
+	//! \~russian Создает пустой массив.
 	PIStack() {}
+
+	//! \~english Puts an element on the stack.
+	//! \~russian Кладёт элемент в стек.
 	PIVector<T> & push(const T & v) {PIVector<T>::push_back(v); return *this;}
+
+	//! \~english Move an element on the stack.
+	//! \~russian Перемещает элемент в стек.
 	PIVector<T> & push(T && v) {PIVector<T>::push_back(std::move(v)); return *this;}
+
+
+	//! \~english Retrieves and returns an element from the stack.
+	//! \~russian Забирает и возвращает элемент из стека.
+	//! \details
+	//! \~\note
+	//! \~english If the stack is empty, it returns the element created by the default constructor.
+	//! \~russian Если стек пустой то возвращает элемент созданный конструткором по умолчанию.
 	T pop() {return PIVector<T>::take_back();}
+
+
+	//! \~english Last element.
+	//! \~russian Последний элемент массива.
+	//! \~\details
+	//! \~english Returns a reference to the last item in the array.
+	//! This function assumes that the array isn't empty.
+	//! Otherwise will be undefined behavior.
+	//! \~russian Возвращает ссылку на последний элемент в массиве.
+	//! Эта функция предполагает, что массив не пустой.
+	//! Иначе это приведёт к неопределённому поведению программы и ошибкам памяти.
 	T & top() {return PIVector<T>::back();}
 	const T & top() const {return PIVector<T>::back();}
+
+	//! \~english Converts \a PIStack to \a PIVector.
+	//! \~russian Преобразует \a PIStack в \a PIVector.
 	PIVector<T> toVector() {return PIVector<T>(*this);}
+
+	//! \~english Converts \a PIStack to \a PIDeque.
+	//! \~russian Преобразует \a PIStack в \a PIDeque.
 	PIDeque<T> toDeque() {return PIDeque<T>(PIVector<T>::data(), PIVector<T>::size());}
 };