some autogen docs

2025-08-14 14:07:52 +03:00
parent d95944dcfc
commit 04152f05a9
7 changed files with 261 additions and 7 deletions
--- a/libs/main/client_server/piclientserver_client.h
+++ b/libs/main/client_server/piclientserver_client.h
@@ -33,6 +33,8 @@ namespace PIClientServer {

 // ServerClient

+//! ~english Server-side client implementation
+//! ~russian Серверная реализация клиента
 class PIP_CLIENT_SERVER_EXPORT ServerClient: public ClientBase {
 	friend class Server;
 	NO_COPY_CLASS(ServerClient);
@@ -41,6 +43,8 @@ public:
 	ServerClient() {}

 protected:
+	//! ~english Called before client destruction
+	//! ~russian Вызывается перед уничтожением клиента
 	virtual void aboutDelete() {}

 private:
@@ -50,6 +54,8 @@ private:

 // Client

+//! ~english Client implementation for connecting to servers
+//! ~russian Клиентская реализация для подключения к серверам
 class PIP_CLIENT_SERVER_EXPORT Client: public ClientBase {
 	NO_COPY_CLASS(Client);

@@ -57,6 +63,8 @@ public:
 	Client();
 	~Client();

+	//! ~english Connects to specified server address
+	//! ~russian Подключается к указанному адресу сервера
 	void connect(PINetworkAddress addr);

 protected:
--- a/libs/main/client_server/piclientserver_client_base.h
+++ b/libs/main/client_server/piclientserver_client_base.h
@@ -37,6 +37,8 @@ class Server;

 class ClientInterface {};

+//! ~english Base class for client-server communication with diagnostics support
+//! ~russian Базовый класс для клиент-серверного взаимодействия с поддержкой диагностики
 // template<bool EnableDiagnostics = false>
 class PIP_CLIENT_SERVER_EXPORT ClientBase {
 	friend class Server;
@@ -46,16 +48,39 @@ public:
 	ClientBase();
 	virtual ~ClientBase();

+	//! ~english Gets underlying TCP connection
+	//! ~russian Возвращает TCP-соединение
 	const PIEthernet * getTCP() const { return tcp; }

+	//! ~english Closes the connection
+	//! ~russian Закрывает соединение
 	void close();
+
+	//! ~english Gracefully stops and waits for completion
+	//! ~russian Плавно останавливает и ожидает завершения
 	void stopAndWait();

+
+	//! ~english Writes byte array to the connection
+	//! ~russian Записывает массив байтов в соединение
 	int write(const void * d, const size_t s);
+
+	//! ~english Writes byte array to the connection
+	//! ~russian Записывает массив байтов в соединение
 	int write(const PIByteArray & ba) { return write(ba.data(), ba.size()); }

+
+	//! ~english Enables diagnostics collection
+	//! ~russian Включает сбор диагностики
 	void enableDiagnostics();
+
+	//! ~english Gets current diagnostics state
+	//! ~russian Возвращает текущее состояние диагностики
 	PIDiagnostics::State diagnostics() const;
+
+
+	//! ~english Gets current received packet bytes already received (all bytes count passed in \a receivePacketStart())
+	//! ~russian Возвращает сколько байт принимаемого пакета получено (общее количество передается в \a receivePacketStart())
 	int receivePacketProgress() const;

 	const PIStreamPackerConfig & configuration() const { return stream.configuration(); }
@@ -63,10 +88,24 @@ public:
 	void setConfiguration(const PIStreamPackerConfig & config) { stream.setConfiguration(config); }

 protected:
+	//! ~english Called when data is received
+	//! ~russian Вызывается при получении данных
 	virtual void readed(PIByteArray data) {}
+
+	//! ~english Called when connection is established
+	//! ~russian Вызывается при установке соединения
 	virtual void connected() {}
+
+	//! ~english Called when connection is closed
+	//! ~russian Вызывается при закрытии соединения
 	virtual void disconnected() {}
+
+	//! ~english Called when packet receiving starts
+	//! ~russian Вызывается при начале получения пакета
 	virtual void receivePacketStart(int size) {}
+
+	//! ~english Called when packet receiving ends
+	//! ~russian Вызывается при завершении получения пакета
 	virtual void receivePacketEnd() {}

 	void init();
--- a/libs/main/client_server/piclientserver_server.h
+++ b/libs/main/client_server/piclientserver_server.h
@@ -38,6 +38,8 @@ namespace PIClientServer {

 class ServerClient;

+//! ~english TCP server for client-server communication
+//! ~russian TCP сервер для клиент-серверного взаимодействия
 class PIP_CLIENT_SERVER_EXPORT Server: public PIStreamPackerConfig {
 	friend class ServerClient;
 	NO_COPY_CLASS(Server);
@@ -46,17 +48,44 @@ public:
 	Server();
 	virtual ~Server();

+	//! ~english Starts listening on specified address
+	//! ~russian Начинает прослушивание на указанном адресе
 	void listen(PINetworkAddress addr);
+
+	//! ~english Starts listening on all interfaces
+	//! ~russian Начинает прослушивание на всех интерфейсах
 	void listenAll(ushort port) { listen({0, port}); }

+
+	//! ~english Stops the server
+	//! ~russian Останавливает сервер
 	void stopServer();
+
+	//! ~english Closes all client connections
+	//! ~russian Закрывает все клиентские соединения
 	void closeAll();

+
+	//! ~english Gets maximum allowed clients
+	//! ~russian Возвращает максимальное число клиентов
 	int getMaxClients() const { return max_clients; }
+
+	//! ~english Sets maximum allowed clients
+	//! ~russian Устанавливает максимальное число клиентов
 	void setMaxClients(int new_max_clients);
+
+	//! ~english Gets current clients count
+	//! ~russian Возвращает текущее количество клиентов
 	int clientsCount() const;
+
+
+	//! ~english Executes function for each connected client
+	//! ~russian Выполняет функцию для каждого подключённого клиента
 	void forEachClient(std::function<void(ServerClient *)> func);

+
+	//! ~english Sets factory for creating new client instances
+	//! ~russian Устанавливает фабрику для создания клиентских экземпляров
 	void setClientFactory(std::function<ServerClient *()> f) { client_factory = f; }

 private:
--- a/libs/main/http_client/pihttpclient.h
+++ b/libs/main/http_client/pihttpclient.h
@@ -13,23 +13,51 @@ public:
 };


+//! ~english Main HTTP client class for performing requests with event callbacks.
+//! ~russian Основной класс HTTP-клиента для выполнения запросов с callback-ми событий.
 class PIP_HTTP_CLIENT_EXPORT PIHTTPClient: private PIHTTPClientBase {
 	friend class PIHTTPClientBase;
 	friend class CurlThreadPool;

 public:
+	//! ~english Creates a new HTTP request instance with the specified URL, method and message.
+	//! ~russian Создает новый экземпляр HTTP-запроса с указанным URL, методом и сообщением.
 	static PIHTTPClient * create(const PIString & url, PIHTTP::Method method = PIHTTP::Method::Get, const PIHTTP::MessageConst & req = {});

+	//! ~english Sets a callback for successful request completion (no parameters).
+	//! ~russian Устанавливает callback для успешного завершения запроса (без параметров).
 	PIHTTPClient * onFinish(std::function<void()> f);
+
+	//! ~english Sets a callback for successful request completion (with response).
+	//! ~russian Устанавливает callback для успешного завершения запроса (с ответом).
 	PIHTTPClient * onFinish(std::function<void(const PIHTTP::MessageConst &)> f);
+
+	//! ~english Sets a callback for request errors (no parameters).
+	//! ~russian Устанавливает callback для ошибок запроса (без параметров).
 	PIHTTPClient * onError(std::function<void()> f);
+
+	//! ~english Sets a callback for request errors (with error response).
+	//! ~russian Устанавливает callback для ошибок запроса (с ответом об ошибке).
 	PIHTTPClient * onError(std::function<void(const PIHTTP::MessageConst &)> f);
+
+	//! ~english Sets a callback for request abortion (no parameters).
+	//! ~russian Устанавливает callback для прерывания запроса (без параметров).
 	PIHTTPClient * onAbort(std::function<void()> f);
+
+	//! ~english Sets a callback for request abortion (with abort response).
+	//! ~russian Устанавливает callback для прерывания запроса (с ответом о прерывании).
 	PIHTTPClient * onAbort(std::function<void(const PIHTTP::MessageConst &)> f);

+	//! ~english Starts the HTTP request execution.
+	//! ~russian Начинает выполнение HTTP-запроса.
 	void start();
+
+	//! ~english Aborts the current HTTP request.
+	//! ~russian Прерывает текущий HTTP-запрос.
 	void abort();

+	//! ~english Returns the last error message.
+	//! ~russian Возвращает последнее сообщение об ошибке.
 	PIString lastError() const { return last_error; }

 private:
--- a/libs/main/http_common/pihttptypes.h
+++ b/libs/main/http_common/pihttptypes.h
@@ -9,20 +9,60 @@
 namespace PIHTTP {


+//! ~english Immutable HTTP message container with accessors for message components
+//! ~russian Контейнер для неизменяемого HTTP-сообщения с методами доступа к компонентам
 class PIP_EXPORT MessageConst {
 public:
+	//! ~english Gets the HTTP method used in the message
+	//! ~russian Возвращает HTTP-метод, использованный в сообщении
 	PIHTTP::Method method() const { return m_method; }
+
+	//! ~english Gets the HTTP status code
+	//! ~russian Возвращает HTTP-статус код
 	PIHTTP::Code code() const { return m_code; }
+
+	//! ~english Checks if status code is informational (1xx)
+	//! ~russian Проверяет, является ли статус код информационным (1xx)
 	bool isCodeInformational() const;
+
+	//! ~english Checks if status code indicates success (2xx)
+	//! ~russian Проверяет, указывает ли статус код на успех (2xx)
 	bool isCodeSuccess() const;
+
+	//! ~english Checks if status code indicates redirection (3xx)
+	//! ~russian Проверяет, указывает ли статус код на перенаправление (3xx)
 	bool isCodeRedirection() const;
+
+	//! ~english Checks if status code indicates client error (4xx)
+	//! ~russian Проверяет, указывает ли статус код на ошибку клиента (4xx)
 	bool isCodeClientError() const;
+
+	//! ~english Checks if status code indicates server error (5xx)
+	//! ~russian Проверяет, указывает ли статус код на ошибку сервера (5xx)
 	bool isCodeServerError() const;
+
+	//! ~english Checks if status code indicates any error (4xx or 5xx)
+	//! ~russian Проверяет, указывает ли статус код на любую ошибку (4xx или 5xx)
 	bool isCodeError() const { return isCodeClientError() || isCodeServerError(); }
+
+	//! ~english Gets the request/response path
+	//! ~russian Возвращает путь запроса/ответа
 	const PIString & path() const { return m_path; }
+
+	//! ~english Gets path components as list
+	//! ~russian Возвращает компоненты пути в виде списка
 	PIStringList pathList() const { return m_path.split('/').removeAll({}); }
+
+	//! ~english Gets the message body
+	//! ~russian Возвращает тело сообщения
 	const PIByteArray & body() const { return m_body; }
+
+	//! ~english Gets all message headers
+	//! ~russian Возвращает все заголовки сообщения
 	const PIMap<PIString, PIString> & headers() const { return m_headers; }
+
+	//! ~english Gets all message arguments
+	//! ~russian Возвращает все аргументы сообщения
 	const PIMap<PIString, PIString> & arguments() const { return m_arguments; }

 protected:
@@ -35,25 +75,60 @@ protected:
 };


+//! ~english Mutable HTTP message container with modifiers for message components
+//! ~russian Контейнер для изменяемого HTTP-сообщения с методами модификации
 class PIP_EXPORT MessageMutable: public MessageConst {
 public:
+	//! ~english Sets the HTTP method
+	//! ~russian Устанавливает HTTP-метод
 	MessageMutable & setMethod(PIHTTP::Method m);
+
+	//! ~english Sets the HTTP status code
+	//! ~russian Устанавливает HTTP-статус код
 	MessageMutable & setCode(PIHTTP::Code c);
+
+	//! ~english Sets the request/response path
+	//! ~russian Устанавливает путь запроса/ответа
 	MessageMutable & setPath(PIString p);
+
+	//! ~english Sets the message body
+	//! ~russian Устанавливает тело сообщения
 	MessageMutable & setBody(PIByteArray b);
+
 	const PIMap<PIString, PIString> & headers() const { return m_headers; }
 	const PIMap<PIString, PIString> & arguments() const { return m_arguments; }
 	PIMap<PIString, PIString> & headers() { return m_headers; }
+
+	//! ~english Adds a header to the message
+	//! ~russian Добавляет заголовок к сообщению
 	MessageMutable & addHeader(const PIString & header, const PIString & value);
+
+	//! ~english Removes a header from the message
+	//! ~russian Удаляет заголовок из сообщения
 	MessageMutable & removeHeader(const PIString & header);
+
 	PIMap<PIString, PIString> & arguments() { return m_arguments; }
+
+	//! ~english Adds an argument to the message
+	//! ~russian Добавляет аргумент к сообщению
 	MessageMutable & addArgument(const PIString & arg, const PIString & value);
+
+	//! ~english Removes an argument from the message
+	//! ~russian Удаляет аргумент из сообщения
 	MessageMutable & removeArgument(const PIString & arg);
+
+	//! ~english Creates message from HTTP status code
+	//! ~russian Создает сообщение из HTTP-статус кода
 	static MessageMutable fromCode(PIHTTP::Code c);
+
+	//! ~english Creates message from HTTP method
+	//! ~russian Создает сообщение из HTTP-метода
 	static MessageMutable fromMethod(PIHTTP::Method m);
 };


+//! ~english Gets string representation of HTTP method
+//! ~russian Возвращает строковое представление HTTP-метода
 PIP_EXPORT const char * methodName(Method m);


--- a/libs/main/http_server/microhttpd_server.h
+++ b/libs/main/http_server/microhttpd_server.h
@@ -7,6 +7,8 @@

 struct MicrohttpdServerConnection;

+//! ~english Base HTTP server class implementing core functionality
+//! ~runnan Базовый класс HTTP сервера, реализующий основную функциональность
 class PIP_HTTP_SERVER_EXPORT MicrohttpdServer: public PIObject {
 	PIOBJECT(MicrohttpdServer)
 	friend struct MicrohttpdServerConnection;
@@ -15,30 +17,75 @@ public:
 	MicrohttpdServer();
 	virtual ~MicrohttpdServer();

+	//! ~english Server configuration options
+	//! ~russian Опции конфигурации сервера
 	enum class Option {
-		ConnectionLimit,   // uint
-		ConnectionTimeout, // uint, sec
-		HTTPSEnabled,      // bool
-		HTTPSMemKey,       // const char * to key.pem data
-		HTTPSMemCert,      // const char * to cert.pem data
-		HTTPSKeyPassword   // const char * to passwd for key.pem
+		ConnectionLimit,   //!< ~english Maximum concurrent connections
+						   //!< ~russian Максимальное количество соединений
+		ConnectionTimeout, //!< ~english Connection timeout in seconds
+						   //!< ~russian Таймаут соединения в секундах
+		HTTPSEnabled,      //!< ~english Enable HTTPS support
+						   //!< ~russian Включить поддержку HTTPS
+		HTTPSMemKey,       //!< ~english SSL key in memory (PIByteArray)
+						   //!< ~russian SSL ключ в памяти (PIByteArray)
+		HTTPSMemCert,      //!< ~english SSL certificate in memory (PIByteArray)
+						   //!< ~russian SSL сертификат в памяти (PIByteArray)
+		HTTPSKeyPassword   //!< ~english SSL key password (PIByteArray)
+						   //!< ~russian Пароль SSL ключа (PIByteArray)
 	};

+	//! ~english Sets server option
+	//! ~russian Устанавливает опцию сервера
 	void setOption(Option o, PIVariant v);
+
+	//! ~english Sets server favicon
+	//! ~russian Устанавливает фавикон сервера
 	void setFavicon(const PIByteArray & im);

+
+	//! ~english Starts server on specified address
+	//! ~russian Запускает сервер на указанном адресе
 	bool listen(PINetworkAddress addr);
+
+	//! ~english Starts server on all interfaces
+	//! ~russian Запускает сервер на всех интерфейсах
 	bool listenAll(ushort port) { return listen({0, port}); }
+
+	//! ~english Checks if server is running
+	//! ~russian Проверяет, работает ли сервер
 	bool isListen() const;
+
+	//! ~english Stops the server
+	//! ~russian Останавливает сервер
 	void stop();

+
+	//! ~english Enables basic authentication
+	//! ~russian Включает базовую аутентификацию
 	void enableBasicAuth() { setBasicAuthEnabled(true); }
+
+	//! ~english Disables basic authentication
+	//! ~russian Выключает базовую аутентификацию
 	void disableBasicAuth() { setBasicAuthEnabled(false); }
+
+	//! ~english Set basic authentication enabled to "yes"
+	//! ~russian Устанавливает базовую аутентификацию в "yes"
 	void setBasicAuthEnabled(bool yes) { use_basic_auth = yes; }
+
+	//! ~english Return if basic authentication enabled
+	//! ~russian Возвращает включена ли базовая аутентификация
 	bool isBasicAuthEnabled() const { return use_basic_auth; }
+
+	//! ~english Sets basic authentication realm
+	//! ~russian Устанавливает область аутентификации
 	void setBasicAuthRealm(const PIString & r) { realm = r; }

+	//! ~english Sets request processing callback
+	//! ~russian Устанавливает callback для обработки запросов
 	void setRequestCallback(std::function<PIHTTP::MessageMutable(const PIHTTP::MessageConst &)> c) { callback = c; }
+
+	//! ~english Sets basic authentication callback
+	//! ~russian Устанавливает callback для базовой аутентификации
 	void setBasicAuthCallback(std::function<bool(const PIString &, const PIString &)> c) { callback_auth = c; }

 private:
--- a/libs/main/http_server/pihttpserver.h
+++ b/libs/main/http_server/pihttpserver.h
@@ -3,6 +3,8 @@

 #include "microhttpd_server.h"

+//! ~english HTTP server
+//! ~russian HTTP сервер
 class PIP_HTTP_SERVER_EXPORT PIHTTPServer: public MicrohttpdServer {
 	PIOBJECT_SUBCLASS(PIHTTPServer, MicrohttpdServer)

@@ -12,24 +14,50 @@ public:

 	using RequestFunction = std::function<PIHTTP::MessageMutable(const PIHTTP::MessageConst &)>;

+
+	//! ~english Registers handler for specific path and HTTP method
+	//! ~russian Регистрирует обработчик для указанного пути и HTTP метода
 	void registerPath(const PIString & path, PIHTTP::Method method, RequestFunction functor);
+
+	//! ~english Registers handler for specific path and HTTP method
+	//! ~russian Регистрирует обработчик для указанного пути и HTTP метода
 	template<typename T>
 	void
 	registerPath(const PIString & path, PIHTTP::Method method, T * o, PIHTTP::MessageMutable (T::*function)(const PIHTTP::MessageConst &)) {
 		registerPath(path, method, [o, function](const PIHTTP::MessageConst & m) { return (o->*function)(m); });
 	}
+
+
+	//! ~english Registers handler for unhandled requests
+	//! ~russian Регистрирует обработчик для необработанных запросов
 	void registerUnhandled(RequestFunction functor);
+
+	//! ~english Registers handler for unhandled requests
+	//! ~russian Регистрирует обработчик для необработанных запросов
 	template<typename T>
 	void registerUnhandled(T * o, PIHTTP::MessageMutable (T::*function)(const PIHTTP::MessageConst &)) {
 		registerUnhandled([o, function](const PIHTTP::MessageConst & m) { return (o->*function)(m); });
 	}
+
+	//! ~english Unregisters handler for specific path and method
+	//! ~russian Удаляет обработчик для указанного пути и метода
 	void unregisterPath(const PIString & path, PIHTTP::Method method);
+
+	//! ~english Unregisters all handlers for specific path
+	//! ~russian Удаляет все обработчики для указанного пути
 	void unregisterPath(const PIString & path);

-	// void registerBasicAuth() {}

+	//! ~english Adds header to all server responses
+	//! ~russian Добавляет заголовок ко всем ответам сервера
 	void addReplyHeader(const PIString & name, const PIString & value) { reply_headers[name] = value; }
+
+	//! ~english Removes header from server responses
+	//! ~russian Удаляет заголовок из ответов сервера
 	void removeReplyHeader(const PIString & name) { reply_headers.remove(name); }
+
+	//! ~english Clears all custom response headers
+	//! ~russian Очищает все пользовательские заголовки ответов
 	void clearReplyHeaders() { reply_headers.clear(); }

 private: