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;