merged AI doc, some new pages

libs/main/system/piplugin.h

@@ -1,9 +1,11 @@
-/*! \file piplugin.h
- * \ingroup System
- * \~\brief
- * \~english Plugin control
- * \~russian Управление плагинами
- */
+//! \~\ingroup System
+//! \~\file piplugin.h
+//! \~\brief
+//! \~english Plugin control
+//! \~russian Управление плагинами
+//! \~\details
+//! \~english Plugin helpers for dynamic library loading and plugin management
+//! \~russian Вспомогательные средства для загрузки динамических библиотек и управления плагинами
 /*
     PIP - Platform Independent Primitives
     Plugin helpers
@@ -34,23 +36,28 @@
 #  ifdef DOXYGEN
 
 
-//! \~english Declare plugin, should be used before other PIP_PLUGIN_* macros
-//! \~russian Объявляет плагин, должен быть использован перед любыми другими PIP_PLUGIN_* макросами
-//! \~\relatesalso PIPluginLoader
+//! \relatesalso PIPluginLoader
+//! \~\brief
+//! \~english Declares plugin entry points and should be used before other \c PIP_PLUGIN_* macros.
+//! \~russian Объявляет точки входа плагина и должен использоваться перед другими макросами \c PIP_PLUGIN_*.
 #	define PIP_PLUGIN
 
-//! \~english Set user version to check it while loading, "version" is quoted string
-//! \~russian Устанавливает пользовательскую версию для проверки во время загрузки, "version" - строка в кавычках
-//! \~\relatesalso PIPluginLoader
+//! \relatesalso PIPluginLoader
+//! \~\brief
+//! \~english Sets user version checked during loading, "version" is quoted string.
+//! \~russian Устанавливает строковую пользовательскую версию, проверяемую при загрузке, "version" - строка в кавычках.
 #	define PIP_PLUGIN_SET_USER_VERSION(version)
 
-//! \~english Add pointer to future merge with plugin. Type is integer
-//! \~russian Добавляет указатель для будущего слияния. Тип - целое число
-//! \~\relatesalso PIPluginLoader
+//! \relatesalso PIPluginLoader
+//! \~\brief
+//! \~english Registers a static section pointer for future merge. \a type is an integer key.
+//! \~russian Регистрирует указатель на статическую секцию для последующего слияния. \a type - целочисленный ключ.
 #	define PIP_PLUGIN_ADD_STATIC_SECTION(type, ptr)
 
-//! \~english Declare function to merge static sections
-//! \~russian Объявляет метод для слияния статических секций
+//! \relatesalso PIPluginLoader
+//! \~\brief
+//! \~english Declares a function that merges plugin and application static sections.
+//! \~russian Объявляет функцию для слияния статических секций плагина и приложения.
 //! \~\details
 //! \~english
 //! This is functions with 3 arguments: (int type, void * from, void * to).
@@ -69,9 +76,10 @@
 //! \~\relatesalso PIPluginLoader
 #	define PIP_PLUGIN_STATIC_SECTION_MERGE
 
-//! \~english Mark method to export
-//! \~russian Пометить метод на экспорт
-//! \~\relatesalso PIPluginLoader
+//! \relatesalso PIPluginLoader
+//! \~\brief
+//! \~english Marks a plugin function for export.
+//! \~russian Помечает функцию плагина для экспорта.
 #	define PIP_PLUGIN_EXPORT
 
 
@@ -117,13 +125,30 @@
 #  endif
 
 
+//! \~\ingroup System
+//! \~\brief
+//! \~english Metadata collected for one plugin or for the host application.
+//! \~russian Метаданные, собираемые для одного плагина или для основного приложения.
 class PIP_EXPORT PIPluginInfo {
 public:
+	//! \~english Constructs empty plugin metadata.
+	//! \~russian Создает пустые метаданные плагина.
 	PIPluginInfo();
 
+	//! \~english Sets user version checked by \a PIPluginLoader::load().
+	//! \~russian Устанавливает пользовательскую версию, проверяемую в \a PIPluginLoader::load().
 	void setUserVersion(const PIString & v);
+
+	//! \~english Associates a static section pointer with integer \a type.
+	//! \~russian Связывает указатель на статическую секцию с целочисленным типом \a type.
 	void setStaticSection(int type, void * ptr);
+
+	//! \~english Returns configured user version string.
+	//! \~russian Возвращает установленную строку пользовательской версии.
 	PIString userVersion() const;
+
+	//! \~english Returns registered static section pointers.
+	//! \~russian Возвращает зарегистрированные указатели статических секций.
 	PIMap<int, void *> staticSections() const;
 
 private:
@@ -132,16 +157,38 @@ private:
 };
 
 
+//! \~\ingroup System
+//! \~\brief
+//! \~english Storage of plugin metadata for the application and loaded plugins.
+//! \~russian Хранилище метаданных плагинов для приложения и загруженных плагинов.
 class PIP_EXPORT PIPluginInfoStorage {
 public:
+	//! \~english Creates storage and initializes application metadata entry.
+	//! \~russian Создает хранилище и инициализирует запись метаданных приложения.
 	PIPluginInfoStorage();
 
+	//! \~english Returns metadata of the current initialization scope.
+	//! \~russian Возвращает метаданные текущей области инициализации.
 	PIPluginInfo * currentInfo();
+
+	//! \~english Returns metadata associated with plugin pointer \a p.
+	//! \~russian Возвращает метаданные, связанные с указателем плагина \a p.
 	PIPluginInfo * pluginInfo(void * p);
+
+	//! \~english Returns metadata entry of the host application.
+	//! \~russian Возвращает запись метаданных основного приложения.
 	PIPluginInfo * applicationInfo();
+
+	//! \~english Enters plugin scope \a p and creates metadata entry if needed.
+	//! \~russian Переходит в область плагина \a p и при необходимости создает запись метаданных.
 	PIPluginInfo * enterPlugin(void * p);
+
+	//! \~english Removes metadata associated with plugin pointer \a p.
+	//! \~russian Удаляет метаданные, связанные с указателем плагина \a p.
 	void unloadPlugin(void * p);
 
+	//! \~english Returns process-wide singleton storage.
+	//! \~russian Возвращает глобальный синглтон хранилища.
 	static PIPluginInfoStorage * instance();
 
 private:
@@ -152,13 +199,21 @@ private:
 };
 
 
-//! \ingroup System
+//! \~\ingroup System
 //! \~\brief
 //! \~english Plugin loader.
 //! \~russian Загрузчик плагина.
+//! \details
+//! \~english Handles dynamic library loading, symbol resolution, and plugin lifecycle management
+//! \~russian Управляет загрузкой динамических библиотек, разрешением символов и жизненным циклом плагинов
 class PIP_EXPORT PIPluginLoader {
 public:
+	//! \~english Signature of the exported loader version function.
+	//! \~russian Сигнатура экспортируемой функции версии загрузчика.
 	typedef int (*FunctionLoaderVersion)();
+
+	//! \~english Signature of the exported static merge function.
+	//! \~russian Сигнатура экспортируемой функции слияния статических секций.
 	typedef void (*FunctionStaticMerge)(int, void *, void *);
 
 	//! \~english Possible load plugin error
@@ -182,8 +237,8 @@ public:
 	~PIPluginLoader();
 
 
-	//! \~english Load plugin with base filename "name"
-	//! \~russian Загружает плагин с базовым именем "name"
+	//! \~english Loads plugin by base filename \a name and updates error state on failure.
+	//! \~russian Загружает плагин по базовому имени файла \a name и обновляет состояние ошибки при неудаче.
 	bool load(const PIString & name);
 
 	//! \~english Unload plugin and free library
@@ -221,8 +276,13 @@ public:
 
 	//! \~english Invoke plugin \a PIP_PLUGIN_STATIC_SECTION_MERGE
 	//! \~russian Вызывает у плагина \a PIP_PLUGIN_STATIC_SECTION_MERGE
+	//! \details
+	//! \~english Calls the plugin's static section merge function to synchronize application and plugin data
+	//! \~russian Вызывает функцию слияния статических секций плагина для синхронизации данных приложения и плагина
 	void mergeStatic();
 
+	//! \~english Returns existing plugin directories for subdirectory \a name.
+	//! \~russian Возвращает существующие каталоги плагинов для подкаталога \a name.
 	static PIStringList pluginsDirectories(const PIString & name);
 
 private: