more ai generated doc with human review

libs/main/state_machine/pistatemachine.h

@@ -1,12 +1,16 @@
-/*! \file pistatemachine.h
- * \ingroup StateMachine
- * \~\brief
- * \~english State machine.
- * \~russian Машина состояний.
- */
+//! \addtogroup StateMachine
+//! \{
+//! \file pistatemachine.h
+//! \brief
+//! \~english State machine.
+//! \~russian Машина состояний.
+//! \details
+//! \~english Main state machine class that manages states and transitions
+//! \~russian Основной класс машины состояний, управляющий состояниями и переходами
+//! \}
 /*
     PIP - Platform Independent Primitives
-	State machine
+    State machine
     Ivan Pelipenko peri4ko@yandex.ru, Andrey Bychkov work.a.b@yandex.ru
 
     This program is free software: you can redistribute it and/or modify
@@ -31,17 +35,36 @@
 
 
 //! \ingroup StateMachine
-//! \~\brief
-//! \~english
-//! \~russian
+//! \~english Main state machine class
+//! \~russian Основной класс машины состояний
 class PIP_EXPORT PIStateMachine: public PIStateBase {
 public:
+	//! \~english Creates state machine with optional name
+	//! \~russian Создает машину состояний с опциональным именем
+	//! \param n Machine name
 	PIStateMachine(const PIString & n = {});
 
+	//! \~english Starts state machine execution
+	//! \~russian Запускает выполнение машины состояний
+	//! \return true if started successfully
 	bool start();
+
+	//! \~english Checks if state machine is running
+	//! \~russian Проверяет, запущена ли машина состояний
+	//! \return true if running
 	bool isRunning() const { return is_running; }
+
+	//! \~english Sets finish callback
+	//! \~russian Устанавливает коллбэк завершения
+	//! \param f Callback function to call when machine finishes
 	void setOnFinish(std::function<void()> f) { on_finish = f; }
 
+	//! \~english Posts event to state machine
+	//! \~russian Отправляет событие в машину состояний
+	//! \tparam Args Event arguments types
+	//! \param event_id Event identifier
+	//! \param args Event arguments
+	//! \return true if transition was triggered
 	template<typename... Args>
 	bool postEvent(int event_id, Args... args) {
 		if (!is_running) return false;

libs/main/state_machine/pistatemachine_base.h

@@ -1,12 +1,16 @@
-/*! \file pistatemachine_base.h
- * \ingroup StateMachine
- * \~\brief
- * \~english Some template helpers for PIStateMachine
- * \~russian Несколько шаблонов для PIStateMachine
- */
+//! \addtogroup StateMachine
+//! \{
+//! \file pistatemachine_base.h
+//! \brief
+//! \~english Some template helpers for PIStateMachine
+//! \~russian Несколько шаблонов для PIStateMachine
+//! \details
+//! \~english Contains helper classes and functions for state machine implementation
+//! \~russian Содержит вспомогательные классы и функции для реализации машины состояний
+//! \}
 /*
     PIP - Platform Independent Primitives
-	Some template helpers for PIStateMachine
+    Some template helpers for PIStateMachine
     Ivan Pelipenko peri4ko@yandex.ru, Andrey Bychkov work.a.b@yandex.ru
 
     This program is free software: you can redistribute it and/or modify
@@ -31,11 +35,19 @@
 
 namespace PIStateMachineHelpers {
 
+//! \~english Helper namespace for state machine implementation
+//! \~russian Вспомогательное пространство имён для реализации машины состояний
+
 //! \~english Base class for function wrappers
 //! \~russian Базовый класс для обёрток функций
 class FunctionBase {
 public:
+	//! \~english Virtual destructor
+	//! \~russian Виртуальный деструктор
 	virtual ~FunctionBase() {}
+
+	//! \~english Returns format hash for type checking
+	//! \~russian Возвращает хеш формата для проверки типов
 	virtual uint formatHash() = 0;
 };
 
@@ -44,15 +56,24 @@ public:
 template<typename... Args>
 class Function: public FunctionBase {
 public:
+	//! \~english Returns format hash for type checking
+	//! \~russian Возвращает хеш формата для проверки типов
 	uint formatHash() override {
 		static uint ret = PIConstChars(typeid(std::function<void(Args...)>).name()).hash();
 		return ret;
 	}
+
+	//! \~english Stored function
+	//! \~russian Сохранённая функция
 	std::function<bool(Args...)> func;
 };
 
 //! \~english Creates function wrapper from std::function
 //! \~russian Создает обёртку функции из std::function
+//! \tparam Ret Return type of the function
+//! \tparam Args Argument types of the function
+//! \param func Function to wrap
+//! \return Pointer to function wrapper
 template<typename Ret, typename... Args>
 FunctionBase * makeFunction(std::function<Ret(Args...)> func) {
 	auto * ret = new Function<Args...>();

libs/main/state_machine/pistatemachine_state.h

@@ -1,12 +1,16 @@
-/*! \file pistatemachine_state.h
- * \ingroup StateMachine
- * \~\brief
- * \~english State machine node
- * \~russian Узел машины состояний
- */
+//! \addtogroup StateMachine
+//! \{
+//! \file pistatemachine_state.h
+//! \brief
+//! \~english State machine node
+//! \~russian Узел машины состояний
+//! \details
+//! \~english Contains state classes for building state machines
+//! \~russian Содержит классы состояний для построения машин состояний
+//! \}
 /*
     PIP - Platform Independent Primitives
-	State machine node
+    State machine node
     Ivan Pelipenko peri4ko@yandex.ru, Andrey Bychkov work.a.b@yandex.ru
 
     This program is free software: you can redistribute it and/or modify
@@ -208,6 +212,11 @@ private:
 };
 
 
+//! \~english Output stream operator for PIStateBase
+//! \~russian Оператор вывода потока для PIStateBase
+//! \param c Output stream
+//! \param s State to output
+//! \return Reference to output stream
 inline PICout operator<<(PICout c, PIStateBase * s) {
 	if (!s)
 		c << "state(nullptr)";

libs/main/state_machine/pistatemachine_transition.h

@@ -1,12 +1,16 @@
-/*! \file pistatemachine_transition.h
- * \ingroup StateMachine
- * \~\brief
- * \~english State machine transition
- * \~russian Переход машины состояний
- */
+//! \addtogroup StateMachine
+//! \{
+//! \file pistatemachine_transition.h
+//! \brief
+//! \~english State machine transition
+//! \~russian Переход машины состояний
+//! \details
+//! \~english Contains transition classes for state machine
+//! \~russian Содержит классы переходов для машины состояний
+//! \}
 /*
     PIP - Platform Independent Primitives
-	State machine transition
+    State machine transition
     Ivan Pelipenko peri4ko@yandex.ru, Andrey Bychkov work.a.b@yandex.ru
 
     This program is free software: you can redistribute it and/or modify
@@ -39,7 +43,13 @@ class PIP_EXPORT PITransitionBase {
 public:
 	//! \~english Creates transition from source to target on event
 	//! \~russian Создает переход от source к target по событию
+	//! \param source Source state
+	//! \param target Target state
+	//! \param event_id Event identifier that triggers this transition
 	PITransitionBase(PIStateBase * source, PIStateBase * target, int event_id);
+
+	//! \~english Virtual destructor
+	//! \~russian Виртуальный деструктор
 	virtual ~PITransitionBase();
 
 	//! \~english Returns state machine this transition belongs to
@@ -114,11 +124,20 @@ protected:
 
 //! \~english Timeout transition
 //! \~russian Переход по таймауту
+//! \details
+//! \~english Transition that triggers after specified timeout
+//! \~russian Переход, который срабатывает после указанного таймаута
 class PIP_EXPORT PITransitionTimeout: public PITransitionBase {
 public:
 	//! \~english Creates timeout transition
 	//! \~russian Создает переход по таймауту
+	//! \param source Source state
+	//! \param target Target state
+	//! \param timeout Timeout duration
 	PITransitionTimeout(PIStateBase * source, PIStateBase * target, PISystemTime timeout);
+
+	//! \~english Destructor
+	//! \~russian Деструктор
 	~PITransitionTimeout();
 
 private:
@@ -128,4 +147,6 @@ private:
 	PITimer timer;
 };
 
+//! \}
+
 #endif