merged AI doc, some new pages

libs/main/io_utils/piparsehelper.h

@@ -1,9 +1,8 @@
-/*! \file piparsehelper.h
- * \ingroup IO
- * \~\brief
- * \~english Helper class to automate structs receive
- * \~russian Класс для автоматизации приема структур
- */
+//! \~\file piparsehelper.h
+//! \~\ingroup IO-Utils
+//! \~\brief
+//! \~english Key-dispatch helper for deserializing packets into callbacks
+//! \~russian Вспомогательный класс диспетчеризации по ключу для десериализации пакетов в обработчики
 /*
     PIP - Platform Independent Primitives
     Helper class to automate structs receive
@@ -30,60 +29,45 @@
 #include "pip_io_utils_export.h"
 
 
-/** \class PIParseHelper
- * \brief Helper class to automate structs receive
- *
- *
- * \section PIParseHelper_synopsis Synopsis
- * This class helps to deserialize and invoke neccessarily methods.
- *
- * Data packets with header and various data types can be automated by this class.
- * Every key value mapped to object member function, lambda-function or functor.
- *
- * This class can remove \b switch-case with deserialization code and
- * replace it with several \a assign() calls, binded to ready-to-use event handlers.
- * Moreover data type automatic takes from event handler or lambda argument. One should
- * only make \"PIByteArray & operator <<()\" with used types, deserialization will be
- * performed by %PIParseHelper.
- *
- *
- * \section PIParseHelper_usage Usage
- *
- * Create instance of %PIParseHelper, or subclass.
- *
- * In \a assign() methods you can use object member function, lambda-function
- * or functor with 0 or 1 arguments,
- *
- *
- * \section PIParseHelper_lambda Lambda-functions
- * \code assign(1, [this](const SomeStruct & s){}) \endcode
- *
- *
- * \section PIParseHelper_examples Examples
- * First example describes subclass variant. As one can see, it`s a single place to change
- * type of received data - event handler argument.
- * \snippet piparsehelper.cpp 0
- *
- * Second example show separate variant:
- * \snippet piparsehelper.cpp 1
- *
- **/
-
+//! \~\ingroup IO-Utils
+//! \~\brief
+//! \~english Maps packet keys to handlers and deserializes payloads before invocation.
+//! \~russian Связывает ключи пакетов с обработчиками и десериализует полезную нагрузку перед вызовом.
+//! \~\details
+//! \~english
+//! %PIParseHelper helps replace manual switch-based packet dispatch with a set of
+//! \a assign() calls. Handlers may be plain callbacks, functors or object member functions.
+//! Payload types are restored from %PIByteArray by the selected handler signature.
+//! \n
+//! \n Example:
+//! \~russian
+//! %PIParseHelper помогает заменить ручную диспетчеризацию пакетов через switch
+//! набором вызовов \a assign(). Обработчиками могут быть обычные callback-функции,
+//! функторы или методы объекта. Тип полезной нагрузки восстанавливается из %PIByteArray
+//! по сигнатуре выбранного обработчика.
+//! \n
+//! \n Пример:
+//!
+//! \~\snippet piparsehelper.cpp 0
+//! \~\snippet piparsehelper.cpp 1
 template<typename Key>
 class PIParseHelper {
 public:
-	//! \brief Construct %PIParseHelper
+	//! \~english Constructs empty parser helper.
+	//! \~russian Создает пустой вспомогательный парсер.
 	PIParseHelper() {}
 
 
-	//! \brief Assign key \"key\" to lambda-function \"func\" without arguments
+	//! \~english Assigns key "key" to callback "func" without payload arguments.
+	//! \~russian Связывает ключ "key" с callback-функцией "func" без аргументов полезной нагрузки.
 	void assign(Key key, std::function<void()> func) {
 		auto lf = [func](PIByteArray) { func(); };
 		functions[key] << lf;
 	}
 
 
-	//! \brief Assign key \"key\" to lambda-function \"func\" with 1 argument
+	//! \~english Assigns key "key" to callback "func" with one deserialized argument.
+	//! \~russian Связывает ключ "key" с callback-функцией "func" с одним десериализуемым аргументом.
 	template<typename T>
 	void assign(Key key, std::function<void(const T &)> func) {
 		auto lf = [func](PIByteArray data) {
@@ -97,7 +81,8 @@ public:
 	}
 
 
-	//! \brief Assign key \"key\" to member function of object \"obj\" without arguments
+	//! \~english Assigns key "key" to zero-argument member function of object "obj".
+	//! \~russian Связывает ключ "key" с методом объекта "obj" без аргументов.
 	template<typename O>
 	void assign(Key key, O * obj, void (O::*member_func)()) {
 		auto lf = [member_func, obj](PIByteArray) { (obj->*member_func)(); };
@@ -105,7 +90,8 @@ public:
 	}
 
 
-	//! \brief Assign key \"key\" to member function of object \"obj\" with 1 argument
+	//! \~english Assigns key "key" to member function of object "obj" with one deserialized argument.
+	//! \~russian Связывает ключ "key" с методом объекта "obj" с одним десериализуемым аргументом.
 	template<typename T, typename O>
 	void assign(Key key, O * obj, void (O::*member_func)(const T &)) {
 		auto lf = [member_func, obj](PIByteArray data) {
@@ -119,14 +105,16 @@ public:
 	}
 
 
-	//! \brief Assign key \"key\" to functor \"func\" with 0 or 1 argument
+	//! \~english Assigns key "key" to functor or lambda with zero or one argument.
+	//! \~russian Связывает ключ "key" с функтором или lambda с нулем или одним аргументом.
 	template<typename L>
 	void assign(Key key, L func) {
 		return assign(key, toStdFunction(func));
 	}
 
 
-	//! \brief Deserialize data and invoke assigned to \"key\" methods
+	//! \~english Deserializes payload "ba" and invokes handlers assigned to "key".
+	//! \~russian Десериализует полезную нагрузку "ba" и вызывает обработчики, назначенные ключу "key".
 	void parse(Key key, PIByteArray ba) {
 		auto fl = functions.value(key);
 		for (auto f: fl)