merged AI doc, some new pages

libs/main/state_machine/pistatemachine.h

@@ -1,13 +1,19 @@
-/*! \file pistatemachine.h
- * \ingroup StateMachine
- * \~\brief
- * \~english State machine.
- * \~russian Машина состояний.
- */
+//! \~\file pistatemachine.h
+//! \brief
+//! \~english State machine.
+//! \~russian Машина состояний.
+//! \details
+//! \~english Main state machine class that manages states and transitions.
+//! \~russian Основной класс машины состояний, управляющий состояниями и переходами.
+//! \note
+//! \~english Thread-safe implementation with nested post handling.
+//! \~russian Потокобезопасная реализация с обработкой вложенных постов.
+//! \~\sa
+//! PIStateBase, PITransitionBase
 /*
     PIP - Platform Independent Primitives
 	State machine
-    Ivan Pelipenko peri4ko@yandex.ru, Andrey Bychkov work.a.b@yandex.ru
+	Ivan Pelipenko peri4ko@yandex.ru
 
     This program is free software: you can redistribute it and/or modify
     it under the terms of the GNU Lesser General Public License as published by
@@ -30,18 +36,32 @@
 #include "pistatemachine_transition.h"
 
 
-//! \ingroup StateMachine
+//! \~\ingroup StateMachine
 //! \~\brief
-//! \~english
-//! \~russian
+//! \~english Root object that owns and runs a hierarchical state machine.
+//! \~russian Корневой объект, который владеет и запускает иерархическую машину состояний.
 class PIP_EXPORT PIStateMachine: public PIStateBase {
 public:
+	//! \~english Creates a state machine with an optional name.
+	//! \~russian Создает машину состояний с необязательным именем.
 	PIStateMachine(const PIString & n = {});
 
+
+	//! \~english Starts the machine from its initial active configuration.
+	//! \~russian Запускает машину из ее начальной активной конфигурации.
 	bool start();
+
+	//! \~english Returns true while the machine is running.
+	//! \~russian Возвращает true, пока машина запущена.
 	bool isRunning() const { return is_running; }
+
+	//! \~english Sets a callback invoked when the machine finishes.
+	//! \~russian Задает callback-функцию, вызываемую при завершении машины.
 	void setOnFinish(std::function<void()> f) { on_finish = f; }
 
+
+	//! \~english Posts an event to active states and triggers the first matching transition.
+	//! \~russian Посылает событие в активные состояния и запускает первый подходящий переход.
 	template<typename... Args>
 	bool postEvent(int event_id, Args... args) {
 		if (!is_running) return false;
@@ -83,6 +103,7 @@ public:
 		return false;
 	}
 
+
 private:
 	void onFinish() override;