merged AI doc, some new pages

2026-03-12 14:46:57 +03:00
parent 07ae277f9e
commit ed13838237
206 changed files with 14088 additions and 5152 deletions
--- a/libs/main/cloud/picloudbase.h
+++ b/libs/main/cloud/picloudbase.h
@@ -1,9 +1,8 @@
-/*! \file picloudbase.h
- * \ingroup Cloud
- * \~\brief
- * \~english Base class for PICloudClient and PICloudServer
- * \~russian Базовый класс для PICloudClient и PICloudServer
- */
+//! \~\file picloudbase.h
+//! \~\ingroup Cloud
+//! \brief
+//! \~english Base class for PICloudClient and PICloudServer.
+//! \~russian Базовый класс для PICloudClient и PICloudServer.
 /*
    PIP - Platform Independent Primitives
    PICloud Base - Base class for PICloudClient and PICloud Server
@@ -30,11 +29,18 @@
 #include "piethernet.h"
 #include "pistreampacker.h"

-
+//! \~\ingroup Cloud
+//! \brief
+//! \~english Base class for cloud client and server.
+//! \~russian Базовый класс для облачного клиента и сервера.
 class PIP_CLOUD_EXPORT PICloudBase {
 public:
+	//! \~english Constructs the shared PICloud transport state.
+	//! \~russian Создает общее транспортное состояние PICloud.
 	PICloudBase();

+	//! \~english Returns the logical server name configured for the transport.
+	//! \~russian Возвращает логическое имя сервера, настроенное для транспорта.
 	PIString serverName() const;

 protected:
--- a/libs/main/cloud/picloudclient.h
+++ b/libs/main/cloud/picloudclient.h
@@ -1,9 +1,8 @@
-/*! \file picloudclient.h
- * \ingroup Cloud
- * \~\brief
- * \~english PICloud Client
- * \~russian Клиент PICloud
- */
+//! \~\file picloudclient.h
+//! \~\ingroup Cloud
+//! \~\brief
+//! \~english Client-side PICloud device for one named server
+//! \~russian Клиентское устройство PICloud для одного именованного сервера
 /*
    PIP - Platform Independent Primitives
    PICloud Client
@@ -29,27 +28,61 @@
 #include "picloudbase.h"
 #include "piconditionvar.h"

-
-//! \brief PICloudClient
-
+//! \~\ingroup Cloud
+//! \~\brief
+//! \~english %PIIODevice implementation for a logical PICloud client.
+//! \~russian Реализация %PIIODevice для логического клиента PICloud.
 class PIP_CLOUD_EXPORT PICloudClient
 	: public PIIODevice
 	, public PICloudBase {
 	PIIODEVICE(PICloudClient, "");

 public:
+	//! \~english Constructs a client for transport endpoint "path" and mode "mode".
+	//! \~russian Создает клиент для транспортной точки "path" и режима "mode".
 	explicit PICloudClient(const PIString & path = PIString(), PIIODevice::DeviceMode mode = PIIODevice::ReadWrite);
+
+	//! \~english Destroys the client and closes the underlying transport.
+	//! \~russian Уничтожает клиент и закрывает нижележащий транспорт.
 	virtual ~PICloudClient();

+
+	//! \~english Sets the logical server name used during the PICloud handshake.
+	//! \~russian Устанавливает логическое имя сервера, используемое при рукопожатии PICloud.
 	void setServerName(const PIString & server_name);
+
+	//! \~english Enables or disables automatic reconnect of the underlying TCP link.
+	//! \~russian Включает или выключает автоматическое переподключение нижележащего TCP-соединения.
 	void setKeepConnection(bool on);
+
+	//! \~english Returns whether the logical PICloud session is established.
+	//! \~russian Возвращает, установлена ли логическая сессия PICloud.
 	bool isConnected() const { return is_connected; }
+
+	//! \~english Returns the number of payload bytes buffered for \a read().
+	//! \~russian Возвращает количество байтов полезной нагрузки, буферизованных для \a read().
 	ssize_t bytesAvailable() const override { return buff.size(); }
+
+	//! \~english Interrupts pending connection and read waits.
+	//! \~russian Прерывает ожидающие операции подключения и чтения.
 	void interrupt() override;

+
+	//! \events
+	//! \{
+
+	//! \fn void connected()
+	//! \~english Raised after the logical PICloud session becomes ready.
+	//! \~russian Вызывается после того, как логическая сессия PICloud готова к работе.
 	EVENT(connected);
+
+	//! \fn void disconnected()
+	//! \~english Raised when the logical PICloud session is closed.
+	//! \~russian Вызывается при закрытии логической сессии PICloud.
 	EVENT(disconnected);

+	//! \}
+
 protected:
 	bool openDevice() override;
 	bool closeDevice() override;
--- a/libs/main/cloud/picloudmodule.h
+++ b/libs/main/cloud/picloudmodule.h
@@ -1,3 +1,13 @@
+/*! \file picloudmodule.h
+ * \ingroup Cloud
+ * \~\brief
+ * \~english Umbrella header for the PICloud module
+ * \~russian Зонтичный заголовок модуля PICloud
+ *
+ * \~\details
+ * \~english Includes the public client, server, and low-level transport helpers of the module.
+ * \~russian Подключает публичные клиентские, серверные и низкоуровневые транспортные помощники модуля.
+ */
 /*
    PIP - Platform Independent Primitives
    Module includes
@@ -18,8 +28,8 @@
 */
 //! \defgroup Cloud Cloud
 //! \~\brief
-//! \~english Cloud transport over ethernet
-//! \~russian Облачный транспорт через ethernet
+//! \~english Named cloud endpoints over an ethernet transport
+//! \~russian Именованные облачные конечные точки поверх Ethernet-транспорта
 //!
 //! \~\details
 //! \~english \section cmake_module_Cloud Building with CMake
@@ -34,10 +44,10 @@
 //! \~russian \par Общее
 //!
 //! \~english
-//! These files provides server-side and client-side of PICloud transport.
+//! Includes logical client and server devices together with low-level PICloud framing helpers.
 //!
 //! \~russian
-//! Эти файлы обеспечивают серверную и клиентскую сторону транспорта PICloud.
+//! Подключает логические клиентские и серверные устройства вместе с низкоуровневыми помощниками кадрирования PICloud.
 //!
 //! \~\authors
 //! \~english
--- a/libs/main/cloud/picloudserver.h
+++ b/libs/main/cloud/picloudserver.h
@@ -1,9 +1,8 @@
-/*! \file picloudserver.h
- * \ingroup Cloud
- * \~\brief
- * \~english PICloud Server
- * \~russian Сервер PICloud
- */
+//! \~\file picloudserver.h
+//! \~\ingroup Cloud
+//! \~\brief
+//! \~english Server-side PICloud device for one named endpoint
+//! \~russian Серверное устройство PICloud для одной именованной конечной точки
 /*
    PIP - Platform Independent Primitives
    PICloud Server
@@ -29,23 +28,43 @@
 #include "picloudbase.h"
 #include "piconditionvar.h"

-
+//! \~\ingroup Cloud
+//! \~\brief
+//! \~english %PIIODevice implementation for a logical PICloud server.
+//! \~russian Реализация %PIIODevice для логического сервера PICloud.
 class PIP_CLOUD_EXPORT PICloudServer
 	: public PIIODevice
 	, public PICloudBase {
 	PIIODEVICE(PICloudServer, "");

 public:
-	//! PICloudServer
+	//! \~english Constructs a logical server for transport endpoint "path" and mode "mode".
+	//! \~russian Создает логический сервер для транспортной точки "path" и режима "mode".
 	explicit PICloudServer(const PIString & path = PIString(), PIIODevice::DeviceMode mode = PIIODevice::ReadWrite);
+
+	//! \~english Destroys the server and closes all logical clients.
+	//! \~russian Уничтожает сервер и закрывает всех логических клиентов.
 	virtual ~PICloudServer();

+
+	//! \~\ingroup Cloud
+	//! \~\brief
+	//! \~english Per-client %PIIODevice exposed by %PICloudServer.
+	//! \~russian Клиентское %PIIODevice, предоставляемое %PICloudServer.
+	//! \~\details
+	//! \~english Instances are created by \a newConnection() and represent one logical cloud client.
+	//! \~russian Экземпляры создаются через \a newConnection() и представляют одного логического облачного клиента.
 	class Client: public PIIODevice {
 		PIIODEVICE(PICloudServer::Client, "");
 		friend class PICloudServer;

 	public:
+		//! \~english Constructs a wrapper for logical client "id" owned by server "srv".
+		//! \~russian Создает обертку для логического клиента "id", принадлежащего серверу "srv".
 		Client(PICloudServer * srv = nullptr, uint id = 0);
+
+		//! \~english Destroys the client wrapper.
+		//! \~russian Уничтожает клиентскую обертку.
 		virtual ~Client();

 	protected:
@@ -67,12 +86,25 @@ public:
 		std::atomic_bool is_connected;
 	};

+	//! \~english Sets the logical server name announced by this server.
+	//! \~russian Устанавливает логическое имя сервера, объявляемое этим сервером.
 	void setServerName(const PIString & server_name);

+	//! \~english Returns a snapshot of the currently connected logical clients.
+	//! \~russian Возвращает снимок текущих подключенных логических клиентов.
 	PIVector<PICloudServer::Client *> clients() const;

+
+	//! \events
+	//! \{
+
+	//! \fn void newConnection(PICloudServer::Client * client)
+	//! \~english Raised when a new logical client appears for this server name.
+	//! \~russian Вызывается, когда для этого имени сервера появляется новый логический клиент.
 	EVENT1(newConnection, PICloudServer::Client *, client);

+	//! \}
+
 protected:
 	bool openDevice() override;
 	bool closeDevice() override;
--- a/libs/main/cloud/picloudtcp.h
+++ b/libs/main/cloud/picloudtcp.h
@@ -1,9 +1,9 @@
-/*! \file picloudtcp.h
- * \ingroup Cloud
- * \~\brief
- * \~english PICloud TCP transport
- * \~russian TCP слой PICloud
- */
+//! \~\file picloudtcp.h
+//! \~\ingroup Cloud
+//! \~\brief
+//! \~english Low-level TCP framing helpers for PICloud
+//! \~russian Низкоуровневые помощники TCP-кадрирования для PICloud
+//!
 /*
    PIP - Platform Independent Primitives
    PICloud TCP transport
@@ -31,50 +31,113 @@
 #include "pistring.h"


-class PIEthernet;
 class PIStreamPacker;

+//! \~\ingroup Cloud
+//! \~english Namespace for low-level PICloud transport helpers.
+//! \~russian Пространство имен для низкоуровневых транспортных помощников PICloud.
 namespace PICloud {


+//! \~\ingroup Cloud
+//! \~\brief
+//! \~english Builds and parses PICloud frames on top of %PIStreamPacker.
+//! \~russian Формирует и разбирает кадры PICloud поверх %PIStreamPacker.
 class PIP_CLOUD_EXPORT TCP {
 public:
+	//! \~english Supported PICloud frame versions.
+	//! \~russian Поддерживаемые версии кадров PICloud.
 	enum Version {
-		Version_1 = 1,
-		Version_2 = 2,
+		Version_1 = 1 /** \~english First protocol version \~russian Первая версия протокола */,
+		Version_2 = 2  /** \~english Current protocol version \~russian Текущая версия протокола */
 	};

+	//! \~english Logical destination role of a PICloud frame.
+	//! \~russian Логическая роль получателя кадра PICloud.
 	enum Role {
-		InvalidRole = 0,
-		Server      = 1,
-		Client      = 2,
+		InvalidRole = 0 /** \~english Invalid or unknown role \~russian Некорректная или неизвестная роль */,
+		Server      = 1 /** \~english Frame for a logical server \~russian Кадр для логического сервера */,
+		Client      = 2 /** \~english Frame for a logical client \~russian Кадр для логического клиента */
 	};

+	//! \~english Kind of PICloud frame payload.
+	//! \~russian Вид полезной нагрузки кадра PICloud.
 	enum Type {
-		InvalidType = 0,
-		Connect     = 1,
-		Disconnect  = 2,
-		Data        = 3,
-		Ping        = 4,
+		InvalidType = 0 /** \~english Invalid or unknown frame \~russian Некорректный или неизвестный кадр */,
+		Connect     = 1 /** \~english Connect or registration frame \~russian Кадр подключения или регистрации */,
+		Disconnect  = 2 /** \~english Disconnect notification frame \~russian Кадр уведомления об отключении */,
+		Data        = 3 /** \~english Payload data frame \~russian Кадр с полезными данными */,
+		Ping        = 4  /** \~english Keepalive frame \~russian Кадр поддержания соединения */
 	};

+
+	//! \~english Constructs a PICloud frame helper bound to packer "s".
+	//! \~russian Создает помощник кадров PICloud, связанный с упаковщиком "s".
 	TCP(PIStreamPacker * s);
+
+	//! \~english Sets the logical role written into outgoing frames.
+	//! \~russian Устанавливает логическую роль, записываемую в исходящие кадры.
 	void setRole(Role r);
+
+	//! \~english Returns the logical role of this helper.
+	//! \~russian Возвращает логическую роль этого помощника.
 	Role role() const { return (Role)header.role; }
+
+	//! \~english Sets the logical server name used by connect and keepalive frames.
+	//! \~russian Устанавливает логическое имя сервера, используемое кадрами подключения и поддержания соединения.
 	void setServerName(const PIString & server_name_);
+
+	//! \~english Returns the configured logical server name.
+	//! \~russian Возвращает настроенное логическое имя сервера.
 	PIString serverName() const;

+
+	//! \~english Sends the initial connect frame for the current server name.
+	//! \~russian Отправляет начальный кадр подключения для текущего имени сервера.
 	void sendStart();
+
+	//! \~english Sends a connect frame for logical client "client_id".
+	//! \~russian Отправляет кадр подключения для логического клиента "client_id".
 	void sendConnected(uint client_id);
+
+	//! \~english Sends a disconnect frame for logical client "client_id".
+	//! \~russian Отправляет кадр отключения для логического клиента "client_id".
 	void sendDisconnected(uint client_id);
+
+	//! \~english Sends a payload frame for the current logical role.
+	//! \~russian Отправляет кадр с полезными данными для текущей логической роли.
 	int sendData(const PIByteArray & data);
+
+	//! \~english Sends a payload frame tagged with logical client "client_id".
+	//! \~russian Отправляет кадр с полезными данными, помеченный логическим клиентом "client_id".
 	int sendData(const PIByteArray & data, uint client_id);
+
+	//! \~english Sends a keepalive frame.
+	//! \~russian Отправляет кадр поддержания соединения.
 	void sendPing();
+
+	//! \~english Parses frame header and returns its type and destination role.
+	//! \~russian Разбирает заголовок кадра и возвращает его тип и роль получателя.
 	PIPair<PICloud::TCP::Type, PICloud::TCP::Role> parseHeader(PIByteArray & ba);
+
+	//! \~english Returns whether current role uses direct payload parsing.
+	//! \~russian Возвращает, использует ли текущая роль прямой разбор полезной нагрузки.
 	bool canParseData(PIByteArray & ba);
+
+	//! \~english Extracts logical client identifier and payload from a server-side data frame.
+	//! \~russian Извлекает идентификатор логического клиента и полезную нагрузку из серверного кадра данных.
 	PIPair<uint, PIByteArray> parseDataServer(PIByteArray & ba);
+
+	//! \~english Validates and returns raw connect payload used for server identity exchange.
+	//! \~russian Проверяет и возвращает сырой payload подключения, используемый при обмене идентичностью сервера.
 	PIByteArray parseConnect_d(PIByteArray & ba);
+
+	//! \~english Extracts logical client identifier from a connect frame.
+	//! \~russian Извлекает идентификатор логического клиента из кадра подключения.
 	uint parseConnect(PIByteArray & ba);
+
+	//! \~english Extracts logical client identifier from a disconnect frame.
+	//! \~russian Извлекает идентификатор логического клиента из кадра отключения.
 	uint parseDisconnect(PIByteArray & ba);

 private: