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/application/piapplicationmodule.h
+++ b/libs/main/application/piapplicationmodule.h
@@ -1,3 +1,13 @@
+/*! \file piapplicationmodule.h
+ * \ingroup Application
+ * \~\brief
+ * \~english Application-level classes.
+ * \~russian Классы уровня "приложение".
+ *
+ * \~\details
+ * \~english Includes the public CLI, logging, single-application, system monitoring, and translation headers.
+ * \~russian Подключает публичные заголовки CLI, логирования, одиночного приложения, системного мониторинга и перевода.
+ */
 /*
    PIP - Platform Independent Primitives
    Module includes
@@ -30,14 +40,14 @@
 //! target_link_libraries([target] PIP)
 //! \endcode
 //!
-//! \~english \par Common
-//! \~russian \par Общее
-//!
 //! \~english
-//! These files provides some classes for help to create application
+//! This umbrella header includes public Application classes for command-line
+//! parsing, logging, single-instance control, process monitoring and translation.
 //!
 //! \~russian
-//! Эти файлы предоставляют классы для облегчения создания приложения
+//! Этот зонтичный заголовок подключает публичные классы Application для
+//! разбора командной строки, ведения лога, контроля одного экземпляра,
+//! мониторинга процесса и перевода.
 //!
 //! \~\authors
 //! \~english
--- a/libs/main/application/picli.h
+++ b/libs/main/application/picli.h
@@ -1,9 +1,8 @@
-/*! \file picli.h
- * \ingroup Application
- * \~\brief
- * \~english Command-Line parser
- * \~russian Парсер командной строки
- */
+//! \~\file picli.h
+//! \~\ingroup Application
+//! \brief
+//! \~english Command-line argument parser
+//! \~russian Парсер аргументов командной строки
 /*
    PIP - Platform Independent Primitives
    Command-Line Parser
@@ -29,10 +28,15 @@
 #include "piset.h"
 #include "pistringlist.h"

-//! \ingroup Application
+//! \~\ingroup Application
 //! \~\brief
-//! \~english Command-Line parser.
-//! \~russian Парсер командной строки.
+//! \~english Command-line argument parser class
+//! \~russian Класс парсера аргументов командной строки
+//! \details
+//! \~english The PICLI class provides convenient parsing of command-line arguments. It supports short keys (e.g., -c), full keys (e.g.,
+//! --console), and arguments with/without values.
+//! \~russian Класс PICLI предоставляет удобный разбор аргументов командной строки. Поддерживаются короткие ключи (например, -c), полные
+//! ключи (например, --console) и аргументы с значениями/без значений.
 class PIP_EXPORT PICLI {
 public:
 	//! \~english Constructs %PICLI from "argc" and "argv" from "int main()" method.
@@ -64,13 +68,25 @@ public:
 	//! \~english Returns unparsed command-line argument by index "index". Index 0 is program execute command.
 	//! \~russian Возвращает исходный аргумент командной строки по индексу "index". Индекс 0 это команда вызова программы.
 	PIString rawArgument(int index);
+
+	//! \~english Returns mandatory positional argument by index.
+	//! \~russian Возвращает обязательный позиционный аргумент по индексу.
 	PIString mandatoryArgument(int index);
+
+	//! \~english Returns optional positional argument by index.
+	//! \~russian Возвращает необязательный позиционный аргумент по индексу.
 	PIString optionalArgument(int index);

 	//! \~english Returns unparsed command-line arguments.
 	//! \~russian Возвращает исходные аргументы командной строки.
 	const PIStringList & rawArguments();
+
+	//! \~english Returns all mandatory positional arguments.
+	//! \~russian Возвращает все обязательные позиционные аргументы.
 	const PIStringList & mandatoryArguments();
+
+	//! \~english Returns all optional positional arguments.
+	//! \~russian Возвращает все необязательные позиционные аргументы.
 	const PIStringList & optionalArguments();

 	//! \~english Returns program execute command without arguments.
@@ -93,18 +109,52 @@ public:
 	//! \~russian Возвращает полный ключ аргумента "name" или пустую строку, если аргумента нет.
 	PIString argumentFullKey(const PIString & name);

+	//! \~english Returns prefix used for short keys.
+	//! \~russian Возвращает префикс коротких ключей.
 	const PIString & shortKeyPrefix() const { return _prefix_short; }
+
+	//! \~english Returns prefix used for full keys.
+	//! \~russian Возвращает префикс полных ключей.
 	const PIString & fullKeyPrefix() const { return _prefix_full; }
+
+	//! \~english Returns expected count of mandatory positional arguments.
+	//! \~russian Возвращает ожидаемое количество обязательных позиционных аргументов.
 	int mandatoryArgumentsCount() const { return _count_mand; }
+
+	//! \~english Returns expected count of optional positional arguments.
+	//! \~russian Возвращает ожидаемое количество необязательных позиционных аргументов.
 	int optionalArgumentsCount() const { return _count_opt; }
+
+	//! \~english Sets prefix used for short keys such as "-d".
+	//! \~russian Устанавливает префикс коротких ключей, например "-d".
 	void setShortKeyPrefix(const PIString & prefix);
+
+	//! \~english Sets prefix used for full keys such as "--debug".
+	//! \~russian Устанавливает префикс полных ключей, например "--debug".
 	void setFullKeyPrefix(const PIString & prefix);
+
+	//! \~english Sets count of mandatory positional arguments collected before optional ones.
+	//! \~russian Устанавливает количество обязательных позиционных аргументов, собираемых до необязательных.
 	void setMandatoryArgumentsCount(const int count);
+
+	//! \~english Sets count of optional positional arguments. Negative value means unlimited.
+	//! \~russian Устанавливает количество необязательных позиционных аргументов. Отрицательное значение означает без ограничения.
 	void setOptionalArgumentsCount(const int count);

+	//! \~english Returns debug mode flag.
+	//! \~russian Возвращает флаг режима отладки.
 	bool debug() const { return debug_; }
+
+	//! \~english Enables or disables debug mode.
+	//! \~russian Включает или выключает режим отладки.
 	void setDebug(bool debug) { debug_ = debug; }
+
+	//! \~english Returns class name.
+	//! \~russian Возвращает имя класса.
 	PIConstChars className() const { return "PICLI"; }
+
+	//! \~english Returns human-readable object name.
+	//! \~russian Возвращает читаемое имя объекта.
 	PIString name() const { return PIStringAscii("CLI"); }

 private:
--- a/libs/main/application/pilog.h
+++ b/libs/main/application/pilog.h
@@ -1,12 +1,11 @@
-/*! \file pilog.h
- * \ingroup Application
- * \~\brief
- * \~english High-level log
- * \~russian Высокоуровневый лог
- */
+//! \~\file pilog.h
+//! \~\ingroup Application
+//! \~\brief
+//! \~english High-level log
+//! \~russian Высокоуровневый лог
 /*
    PIP - Platform Independent Primitives
-	High-level log
+    High-level log
    Ivan Pelipenko peri4ko@yandex.ru

    This program is free software: you can redistribute it and/or modify
@@ -30,15 +29,23 @@
 #include "piiostream.h"
 #include "pithread.h"

-//! \ingroup Application
+//! \~\ingroup Application
 //! \~\brief
 //! \~english High-level log
 //! \~russian Высокоуровневый лог
+//! \~\details
+//! \~english Provides log with optional file and console output, with configurable timestamp format and line format.
+//! \~russian Предоставляет лог с опциональным выводом в файл и консоль, с настраиваемым форматом метки времени и форматом строки.
 class PIP_EXPORT PILog: public PIThread {
 	PIOBJECT_SUBCLASS(PILog, PIThread)

 public:
+	//! \~english Constructs log with console output, timestamped lines and rotated log files.
+	//! \~russian Создает лог с выводом в консоль, строками с метками времени и ротацией файлов.
 	PILog();
+
+	//! \~english Stops logging thread and flushes queued messages.
+	//! \~russian Останавливает поток логирования и дописывает сообщения из очереди.
 	~PILog();

 	//! \~english Message category
@@ -58,8 +65,8 @@ public:
 		All /** \~english All \~russian Все */             = 0xFF,
 	};

-	//! \~english Set output channel \"o\" to \"on\".
-	//! \~russian Установить канал вывода \"o\" в \"on\".
+	//! \~english Enables or disables output channel "o".
+	//! \~russian Включает или выключает канал вывода "o".
 	void setOutput(Output o, bool on = true) { output.setFlag(o, on); }

 	//! \~english Returns prefix for filename.
@@ -80,7 +87,7 @@ public:


 	//! \~english Returns directory for log files.
-	//! \~russian Возвращает директорию для файлов.
+	//! \~russian Возвращает директорию файлов лога.
 	PIString dir() const { return log_dir; }

 	//! \~english Set directory for log files. Should be set \b after \a setLogName()!
@@ -92,8 +99,8 @@ public:
 	//! \~russian Возвращает время жизни файла.
 	PISystemTime fileSplitTime() const { return split_time; }

-	//! \~english Set lifetime for file. Each "st" interval new file will be created.
-	//! \~russian Устанавливает время жизни файла. Каждый интервал "st" будет создан новый файл.
+	//! \~english Sets log file rotation interval. A new file is created every "st".
+	//! \~russian Устанавливает интервал ротации файла лога. Новый файл создается каждые "st".
 	void setFileSplitTime(PISystemTime st) { split_time = st; }


@@ -110,8 +117,8 @@ public:
 	//! \~russian Возвращает формат строки.
 	PIString lineFormat() const { return line_format; }

-	//! \~english Set line format. "t" is timestamp, "c" is category and "m" is message. Default is "t - c: m".
-	//! \~russian Устанавливает формат строки. "t" - метка времени, "c" - категория и "m" - сообщение. По умолчанию "t - c: m".
+	//! \~english Sets line format. "t" is timestamp, "c" is category and "m" is message. Default is "t - c: m".
+	//! \~russian Устанавливает формат строки. "t" - метка времени, "c" - категория, "m" - сообщение. По умолчанию "t - c: m".
 	void setLineFormat(const PIString & f);


@@ -119,9 +126,8 @@ public:
 	//! \~russian Возвращает максимальную категорию.
 	Level level() const { return max_level; }

-	//! \~english Set maximum level. All levels greater than \"l\" will be ignored. Default is \a Level::Debug.
-	//! \~russian Устанавливает максимальную категорию. Все сообщения с большей категорией, чем \"l\", будут игнорироваться. По умолчанию \a
-	//! Level::Debug.
+	//! \~english Sets maximum accepted level. Messages above "l" are ignored. Default is \a Level::Debug.
+	//! \~russian Устанавливает максимальный принимаемый уровень. Сообщения выше "l" игнорируются. По умолчанию \a Level::Debug.
 	void setLevel(Level l);

 	//! \~english Returns \a PICout for \a Level::Error level.
@@ -140,12 +146,12 @@ public:
 	//! \~russian Возвращает \a PICout для категории \a Level::Debug.
 	PICout debug(PIObject * context = nullptr);

-	//! \~english Write all queued lines and stop. Also called in destructor.
-	//! \~russian Записывает все строки из очереди и останавливается. Также вызывается в деструкторе.
+	//! \~english Writes all queued lines and stops logging. Also called from destructor.
+	//! \~russian Записывает все строки из очереди и останавливает логирование. Также вызывается из деструктора.
 	void stop();

-	//! \~english Read all previous and current log content and returns them as %PIStringList.
-	//! \~russian Читает все предыдущие и текущий логи и возвращает их как %PIStringList.
+	//! \~english Reads all rotated and current log lines and returns them as %PIStringList.
+	//! \~russian Читает строки из текущего и уже ротированных логов и возвращает их как %PIStringList.
 	PIStringList readAllLogs() const;

 private:
--- a/libs/main/application/pisingleapplication.h
+++ b/libs/main/application/pisingleapplication.h
@@ -1,9 +1,8 @@
-/*! \file pisingleapplication.h
- * \ingroup Application
- * \~\brief
- * \~english Single-instance application control
- * \~russian Контроль одного экземпляра приложения
- */
+//! \~\file pisingleapplication.h
+//! \~\ingroup Application
+//! \~\brief
+//! \~english Single-instance application control
+//! \~russian Контроль одного экземпляра приложения
 /*
    PIP - Platform Independent Primitives
    Single application
@@ -30,35 +29,44 @@

 class PISharedMemory;

-//! \ingroup Application
+//! \~\ingroup Application
 //! \~\brief
 //! \~english Single-instance application control.
 //! \~russian Контроль одного экземпляра приложения.
+//! \~\details
+//! \~english The PISingleApplication class provides single-instance application control. It allows detecting if the current application
+//! instance is the first one launched and enables inter-process communication between multiple instances. Multiple instances with the same
+//! "app_name" can detect each other and communicate. The first instance becomes the server, receiving messages from subsequent instances.
+//! \~russian Класс PISingleApplication предоставляет контроль одного экземпляра приложения. Он позволяет определить, является ли текущий
+//! экземпляр первым запущенным, и обеспечивает межпроцессное взаимодействие между несколькими экземплярами. Несколько экземпляров с
+//! одинаковым "app_name" могут обнаруживать друг друга и обмениваться сообщениями. Первый экземпляр становится сервером, принимающим
+//! сообщения от последующих экземпляров.
+
 class PIP_EXPORT PISingleApplication: public PIThread {
 	PIOBJECT_SUBCLASS(PISingleApplication, PIThread);

 public:
-	//! \~english Construct %PISingleApplication with name "app_name"
-	//! \~russian Создает %PISingleApplication с именем "app_name"
+	//! \~english Constructs %PISingleApplication for application name "app_name".
+	//! \~russian Создает %PISingleApplication для имени приложения "app_name".
 	PISingleApplication(const PIString & app_name = PIString());

+	//! \~english Stops instance monitoring and releases shared resources.
+	//! \~russian Останавливает мониторинг экземпляра и освобождает общие ресурсы.
 	~PISingleApplication();


-	//! \~english Returns if this application instance is launched first
-	//! \~russian Возвращает первым ли был запущен этот экземпляр приложения
+	//! \~english Returns whether this process is the first launched instance.
+	//! \~russian Возвращает, является ли этот процесс первым запущенным экземпляром.
 	bool isFirst() const;

-	EVENT_HANDLER1(void, sendMessage, const PIByteArray &, m);
-	EVENT1(messageReceived, PIByteArray, m);
-
 	//! \handlers
 	//! \{

 	//! \fn void sendMessage(const PIByteArray & m)
 	//! \brief
-	//! \~english Send message "m" to first launched application
-	//! \~russian Посылает сообщение "m" первому запущеному приложению
+	//! \~english Sends message "m" to the first launched application instance
+	//! \~russian Посылает сообщение "m" первому запущенному экземпляру приложения
+	EVENT_HANDLER1(void, sendMessage, const PIByteArray &, m);

 	//! \}
 	//! \events
@@ -66,8 +74,9 @@ public:

 	//! \fn void messageReceived(PIByteArray m)
 	//! \brief
-	//! \~english Raise on first launched application receive message from another
-	//! \~russian Вызывается первым запущеным приложением по приему сообщения от других
+	//! \~english Emitted by the first launched application when receiving a message from another instance
+	//! \~russian Вызывается первым запущенным приложением при получении сообщения от другого экземпляра
+	EVENT1(messageReceived, PIByteArray, m);

 	//! \}

--- a/libs/main/application/pisystemmonitor.h
+++ b/libs/main/application/pisystemmonitor.h
@@ -1,9 +1,8 @@
-/*! \file pisystemmonitor.h
- * \ingroup Application
- * \~\brief
- * \~english System resources monitoring
- * \~russian Мониторинг ресурсов системы
- */
+//! \~\file pisystemmonitor.h
+//! \~\ingroup Application
+//! \brief
+//! \~english System resources monitoring
+//! \~russian Мониторинг ресурсов системы
 /*
    PIP - Platform Independent Primitives
    Process resource monitor
@@ -30,23 +29,30 @@
 #include "pithread.h"


-//! \ingroup Application
+//! \~\ingroup Application
 //! \~\brief
-//! \~english Process monitoring.
-//! \~russian Мониторинг процесса.
+//! \~english Process and thread resource monitoring.
+//! \~russian Мониторинг ресурсов процесса и его потоков.
+//! \details
+//! \~english This module provides process and system resource monitoring capabilities including CPU usage, memory consumption, and thread
+//! statistics. It supports cross-platform monitoring on Linux, Windows, macOS, and ESP platforms.
+//! \~russian Этот модуль предоставляет возможности мониторинга ресурсов процессов и системы, включая использование CPU, потребление памяти
+//! и статистику потоков. Поддерживается кроссплатформенный мониторинг на Linux, Windows, macOS и ESP платформах.
 class PIP_EXPORT PISystemMonitor: public PIThread {
 	PIOBJECT_SUBCLASS(PISystemMonitor, PIThread);
 	friend class PIIntrospectionServer;

 public:
-	//! \~english Constructs unassigned %PISystemMonitor
-	//! \~russian Создает непривязанный %PISystemMonitor
+	//! \~english Constructs unassigned %PISystemMonitor.
+	//! \~russian Создает непривязанный %PISystemMonitor.
 	PISystemMonitor();

+	//! \~english Stops monitoring and detaches from the current process target.
+	//! \~russian Останавливает мониторинг и отсоединяет объект от текущей цели.
 	~PISystemMonitor();

 #pragma pack(push, 1)
-	//! \ingroup Application
+	//! \~\ingroup Application
 	//! \~\brief
 	//! \~english Process statistics (fixed-size fields).
 	//! \~russian Статистика процесса (фиксированные поля).
@@ -95,16 +101,16 @@ public:
 		//! \~russian Память данных в байтах
 		ullong data_memsize     = 0;

-		//! \~english
-		//! \~russian
+		//! \~english Total RAM in bytes.
+		//! \~russian Общий объем RAM в байтах.
 		ullong ram_total        = 0;

-		//! \~english
-		//! \~russian
+		//! \~english Free RAM in bytes.
+		//! \~russian Свободный объем RAM в байтах.
 		ullong ram_free         = 0;

-		//! \~english
-		//! \~russian
+		//! \~english Used RAM in bytes.
+		//! \~russian Используемый объем RAM в байтах.
 		ullong ram_used         = 0;

 		//! \~english CPU load in kernel space
@@ -116,7 +122,7 @@ public:
 		float cpu_load_user     = 0.f;
 	};

-	//! \ingroup Application
+	//! \~\ingroup Application
 	//! \~\brief
 	//! \~english Thread statistics (fixed-size fields).
 	//! \~russian Статистика потока (фиксированные поля).
@@ -151,13 +157,13 @@ public:
 	};
 #pragma pack(pop)

-	//! \ingroup Application
+	//! \~\ingroup Application
 	//! \~\brief
 	//! \~english Process statistics.
 	//! \~russian Статистика процесса.
 	struct PIP_EXPORT ProcessStats: ProcessStatsFixed {
-		//! \~english Fill human-readable fields
-		//! \~russian Заполнить читаемые поля
+		//! \~english Fills human-readable memory size fields.
+		//! \~russian Заполняет поля с человекочитаемыми размерами памяти.
 		void makeStrings();

 		//! \~english Execution command
@@ -189,7 +195,7 @@ public:
 		PIString data_memsize_readable;
 	};

-	//! \ingroup Application
+	//! \~\ingroup Application
 	//! \~\brief
 	//! \~english Thread statistics.
 	//! \~russian Статистика потока.
@@ -201,51 +207,59 @@ public:

 #ifndef MICRO_PIP

-	//! \~english Starts monitoring of process with PID "pID" and update interval "interval_ms" milliseconds
-	//! \~russian Начинает мониторинг процесса с PID "pID" и интервалом обновления "interval_ms" миллисекунд
+	//! \~english Starts monitoring the process with PID "pID" using the given update interval.
+	//! \~russian Запускает мониторинг процесса с PID "pID" с указанным интервалом обновления.
 	bool startOnProcess(int pID, PISystemTime interval = PISystemTime::fromSeconds(1.));
 #endif

-	//! \~english Starts monitoring of application process with update interval "interval_ms" milliseconds
-	//! \~russian Начинает мониторинг процесса приложения с интервалом обновления "interval_ms" миллисекунд
+	//! \~english Starts monitoring the current application process.
+	//! \~russian Запускает мониторинг текущего процесса приложения.
 	bool startOnSelf(PISystemTime interval = PISystemTime::fromSeconds(1.));

-	//! \~english Stop monitoring
-	//! \~russian Останавливает мониторинг
+	//! \~english Stops monitoring.
+	//! \~russian Останавливает мониторинг.
 	void stop();


-	//! \~english Returns monitoring process PID
-	//! \~russian Возвращает PID наблюдаемого процесса
+	//! \~english Returns PID of the monitored process.
+	//! \~russian Возвращает PID наблюдаемого процесса.
 	int pID() const { return pID_; }

-	//! \~english Returns monitoring process statistics
-	//! \~russian Возвращает статистику наблюдаемого процесса
+	//! \~english Returns latest process statistics snapshot.
+	//! \~russian Возвращает последний снимок статистики процесса.
 	ProcessStats statistic() const;

-	//! \~english Returns monitoring process threads statistics
-	//! \~russian Возвращает статистику потоков наблюдаемого процесса
+	//! \~english Returns latest per-thread statistics snapshot.
+	//! \~russian Возвращает последний снимок статистики по потокам.
 	PIVector<ThreadStats> threadsStatistic() const;

+	//! \~english Replaces current process statistics with external data.
+	//! \~russian Заменяет текущую статистику процесса внешними данными.
 	void setStatistic(const ProcessStats & s);


-	//! \~english
-	//! \~russian
+	//! \~english Returns total RAM in bytes on supported platforms.
+	//! \~russian Возвращает общий объем RAM в байтах на поддерживаемых платформах.
 	static ullong totalRAM();

-	//! \~english
-	//! \~russian
+	//! \~english Returns free RAM in bytes on supported platforms.
+	//! \~russian Возвращает свободный объем RAM в байтах на поддерживаемых платформах.
 	static ullong freeRAM();

-	//! \~english
-	//! \~russian
+	//! \~english Returns used RAM in bytes on supported platforms.
+	//! \~russian Возвращает используемый объем RAM в байтах на поддерживаемых платформах.
 	static ullong usedRAM();

-	//! \~english
-	//! \~russian
+	//! \~\events
+	//! \~\{
+
+	//! \~\fn void measured()
+	//! \~english Raised after a new statistics snapshot is measured.
+	//! \~russian Вызывается после измерения нового снимка статисти
 	EVENT(measured);

+	//! \~\}
+
 private:
 	void run() override;
 	void gatherThread(llong id);
--- a/libs/main/application/pitranslator.h
+++ b/libs/main/application/pitranslator.h
@@ -1,9 +1,8 @@
-/*! \file pitranslator.h
- * \ingroup Application
- * \~\brief
- * \~english Translation support
- * \~russian Поддержка перевода
- */
+//! \~\file pitranslator.h
+//! \~\ingroup Application
+//! \brief
+//! \~english Translation support
+//! \~russian Поддержка перевода
 /*
    PIP - Platform Independent Primitives
 	Translation support
@@ -29,24 +28,74 @@
 #include "pistring.h"


-#define piTr     PITranslator::tr
-#define piTrNoOp PITranslator::trNoOp
+#ifdef DOXYGEN

-//! \ingroup Application
+//! \relatesalso PITranslator
+//! \~\brief
+//! \~english Alias to \a PITranslator::tr().
+//! \~russian Алиас к \a PITranslator::tr().
+#  define piTr
+
+//! \relatesalso PITranslator
+//! \~\brief
+//! \~english Alias to \a PITranslator::trNoOp().
+//! \~russian Алиас к \a PITranslator::trNoOp().
+#  define piTrNoOp
+
+#else
+
+#  define piTr     PITranslator::tr
+#  define piTrNoOp PITranslator::trNoOp
+
+#endif
+
+//! \~\ingroup Application
 //! \~\brief
 //! \~english Translation support
 //! \~russian Поддержка перевода
+//! \~\details
+//! \~english Provides translation support with context-aware string wrappers and multiple loading methods.
+//! %PITranslator stores loaded translations in a process-wide singleton.
+//! If translation or context is missing, the source string is returned unchanged.
+//! \~russian Предоставляет поддержку перевода с контекстно-зависимыми обертками строк и методами загрузки.
+//! %PITranslator хранит загруженные переводы в синглтоне процесса.
+//! Если перевод или контекст не найдены, исходная строка возвращается без изменений.
 class PIP_EXPORT PITranslator {
 public:
+	//! \~english Returns translated string for "in" in optional "context".
+	//! \~russian Возвращает перевод строки "in" в необязательном "context".
 	static PIString tr(const PIString & in, const PIString & context = {});
+
+	//! \~english Converts UTF-8 string literal to %PIString and translates it.
+	//! \~russian Преобразует UTF-8 строковый литерал в %PIString и переводит его.
 	static PIString tr(const char * in, const PIString & context = {}) { return tr(PIString::fromUTF8(in), context); }
+
+	//! \~english Marks string for translation-aware code paths and returns it unchanged.
+	//! \~russian Помечает строку для кода, работающего с переводом, и возвращает ее без изменений.
 	static PIString trNoOp(const PIString & in, const PIString & context = {}) { return in; }
+
+	//! \~english UTF-8 overload of \a trNoOp().
+	//! \~russian UTF-8 перегрузка для \a trNoOp().
 	static PIString trNoOp(const char * in, const PIString & context = {}) { return trNoOp(PIString::fromUTF8(in), context); }

+	//! \~english Clears all loaded translations.
+	//! \~russian Очищает все загруженные переводы.
 	static void clear();
+
+	//! \~english Clears current translations and loads language files matching "short_lang" from "dir".
+	//! \~russian Очищает текущие переводы и загружает языковые файлы, соответствующие "short_lang", из "dir".
 	static void loadLang(const PIString & short_lang, PIString dir = {});
+
+	//! \~english Loads translations from textual configuration content.
+	//! \~russian Загружает переводы из текстового конфигурационного содержимого.
 	static void loadConfig(const PIString & content);
+
+	//! \~english Loads translations from binary content in PIP translation format.
+	//! \~russian Загружает переводы из бинарного содержимого в формате переводов PIP.
 	static bool load(const PIByteArray & content);
+
+	//! \~english Loads translations from file and checks its translation header.
+	//! \~russian Загружает переводы из файла и проверяет его заголовок переводов.
 	static bool loadFile(const PIString & path);

 private:
@@ -59,10 +108,24 @@ private:
 };


+//! \~\ingroup Application
+//! \~\brief
+//! \~english Context-aware string wrapper that automatically translates strings using PITranslator::tr().
+//! Helper returned by \a operator""_tr for optional-context translation.
+//! \~russian Контекстно-зависимая обертка строки, автоматически переводящая строки с помощью PITranslator::tr().
+//! Вспомогательный тип, возвращаемый \a operator""_tr для перевода с необязательным контекстом.
 class PIStringContextTr {
 public:
+	//! \~english Stores source string for later translation.
+	//! \~russian Сохраняет исходную строку для последующего перевода.
 	PIStringContextTr(PIString && s): _s(s) {}
+
+	//! \~english Translates stored string without explicit context.
+	//! \~russian Переводит сохраненную строку без явного контекста.
 	operator PIString() const { return PITranslator::tr(_s); }
+
+	//! \~english Translates stored string in context "ctx".
+	//! \~russian Переводит сохраненную строку в контексте "ctx".
 	PIString operator()(const PIString & ctx = {}) const { return PITranslator::tr(_s, ctx); }

 private:
@@ -70,10 +133,24 @@ private:
 };


+//! \~\ingroup Application
+//! \~\brief
+//! \~english Context-aware string wrapper that preserves original strings without translation (no-op).
+//! Helper returned by \a operator""_trNoOp that keeps source text unchanged.
+//! \~russian Контекстно-зависимая обертка строки, сохраняющая оригинальные строки без перевода (заглушка).
+//! Вспомогательный тип, возвращаемый \a operator""_trNoOp, который сохраняет исходный текст без изменений.
 class PIStringContextTrNoOp {
 public:
+	//! \~english Stores source string without translating it.
+	//! \~russian Сохраняет исходную строку без перевода.
 	PIStringContextTrNoOp(PIString && s): _s(s) {}
+
+	//! \~english Returns stored string unchanged.
+	//! \~russian Возвращает сохраненную строку без изменений.
 	operator PIString() const { return _s; }
+
+	//! \~english Returns stored string unchanged and ignores "ctx".
+	//! \~russian Возвращает сохраненную строку без изменений и игнорирует "ctx".
 	PIString operator()(const PIString & ctx = {}) const { return _s; }

 private:
@@ -82,15 +159,17 @@ private:


 //! \~\brief
-//! \~english Translate string with \a PITranslator::tr()
-//! \~russian Перевести строку с помощью \a PITranslator::tr()
+//! \~english User-defined literal that defers translation through \a PITranslator::tr().
+//! \~russian Пользовательский литерал, откладывающий перевод через \a PITranslator::tr().
+//! \~\code "hello"_tr \endcode
 inline PIStringContextTr operator""_tr(const char * v, size_t sz) {
 	return PIStringContextTr(PIString::fromUTF8(v, sz));
 }

 //! \~\brief
-//! \~english Translate string with \a PITranslator::tr()
-//! \~russian Перевести строку с помощью \a PITranslator::tr()
+//! \~english User-defined literal that keeps source text unchanged via \a PITranslator::trNoOp().
+//! \~russian Пользовательский литерал, сохраняющий исходный текст без изменений через \a PITranslator::trNoOp().
+//! \~\code "hello"_trNoOp \endcode
 inline PIStringContextTrNoOp operator""_trNoOp(const char * v, size_t sz) {
 	return PIStringContextTrNoOp(PIString::fromUTF8(v, sz));
 }