more ai generated doc with human review

2026-02-28 12:29:00 +03:00
parent 077f12c9e5
commit 0878891cd8
86 changed files with 2215 additions and 637 deletions
--- a/libs/main/introspection/piintrospection_base.h
+++ b/libs/main/introspection/piintrospection_base.h
@@ -61,12 +61,17 @@ class PIIntrospection;
 class PIIntrospectionServer;

 #if defined(PIP_INTROSPECTION) && !defined(PIP_FORCE_NO_PIINTROSPECTION)
+
+//! \~english Declare singleton interface for introspection module T
+//! \~russian Объявить интерфейс-синглтон для интроспекции модуля T
 #  define __PIINTROSPECTION_SINGLETON_H__(T) static PIIntrospection##T##Interface * instance();

-#  define __PIINTROSPECTION_SINGLETON_CPP__(T)                                    \
-	  PIIntrospection##T##Interface * PIIntrospection##T##Interface::instance() { \
-		  static PIIntrospection##T##Interface ret;                               \
-		  return &ret;                                                            \
-	  }
+//! \~english Implement singleton interface for introspection module T
+//! \~russian Реализовать интерфейс-синглтон для интроспекции модуля T
+#  define __PIINTROSPECTION_SINGLETON_CPP__(T)                                  \
+	PIIntrospection##T##Interface * PIIntrospection##T##Interface::instance() { \
+	  static PIIntrospection##T##Interface ret;                                 \
+	  return &ret;                                                              \
+	}
 #endif // PIP_INTROSPECTION
 #endif // PIINTROSPECTION_BASE_H
--- a/libs/main/introspection/piintrospection_containers.h
+++ b/libs/main/introspection/piintrospection_containers.h
@@ -3,44 +3,67 @@
    Introspection module - interface for containers
    Ivan Pelipenko peri4ko@yandex.ru

-    This program is free software: you can redistribute it and/or modify
-    it under the terms of the GNU Lesser General Public License as published by
-    the Free Software Foundation, either version 3 of the License, or
-    (at your option) any later version.
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Lesser General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.

-    This program is distributed in the hope that it will be useful,
-    but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU Lesser General Public License for more details.
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Lesser General Public License for more details.

-    You should have received a copy of the GNU Lesser General Public License
-    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ You should have received a copy of the GNU Lesser General Public License
+ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
+//! \addtogroup Introspection
+//! \{
+//! \file piintrospection_containers.h
+//! \brief Container introspection
+//! \~english Interface for container introspection and memory tracking
+//! \~russian Интерфейс для интроспекции контейнеров и отслеживания памяти
+//! \details
+//! \~english Provides interface for tracking container memory allocations and usage
+//! \~russian Предоставляет интерфейс для отслеживания выделения и использования памяти контейнерами

 #ifndef PIINTROSPECTION_CONTAINERS_H
-#define PIINTROSPECTION_CONTAINERS_H
+#  define PIINTROSPECTION_CONTAINERS_H

-#include "pibase.h"
+#  include "pibase.h"

+//! \~english Container type information structure
+//! \~russian Структура информации о типе контейнера
 struct PIP_EXPORT PIIntrospectionContainersType {
 	~PIIntrospectionContainersType();
 	void finish();
+	//! \~english Type identifier
+	//! \~russian Идентификатор типа
 	uint id                = 0;
+	//! \~english Type name
+	//! \~russian Имя типа
 	const char * name      = nullptr;
+	//! \~english Demangled type name
+	//! \~russian Демангл-имя типа
 	const char * demangled = "?";
+	//! \~english Initialization flag
+	//! \~russian Флаг инициализации
 	bool inited            = false;
+	//! \~english Has demangled name flag
+	//! \~russian Флаг наличия demangled имени
 	bool has_demangled     = false;
 };

-#if defined(PIP_INTROSPECTION) && !defined(PIP_FORCE_NO_PIINTROSPECTION)
+#  if defined(PIP_INTROSPECTION) && !defined(PIP_FORCE_NO_PIINTROSPECTION)

-#  include "piintrospection_base.h"
-
-class PIIntrospectionContainers;
+#	include "piintrospection_base.h"

+//! \~english Container type information template
+//! \~russian Шаблон информации о типе контейнера
 template<typename T>
 class PIIntrospectionContainersTypeInfo {
 public:
+	//! \~english Get container type information
+	//! \~russian Получить информацию о типе контейнера
 	static const PIIntrospectionContainersType & get() {
 		static PIIntrospectionContainersType ret = create();
 		return ret;
@@ -55,7 +78,7 @@ private:
 	}
 };

-#  define PIINTROSPECTION_CONTAINERS (PIIntrospectionContainersInterface::instance())
+#	define PIINTROSPECTION_CONTAINERS (PIIntrospectionContainersInterface::instance())

 // clang-format off
 #  define PIINTROSPECTION_CONTAINER_NEW(t, isz)    PIINTROSPECTION_CONTAINERS->containerNew   (PIIntrospectionContainersTypeInfo<t>::get(), isz);
@@ -67,6 +90,8 @@ private:
 // clang-format on


+//! \~english Container introspection interface
+//! \~russian Интерфейс интроспекции контейнеров
 class PIP_EXPORT PIIntrospectionContainersInterface {
 	friend class PIIntrospection;
 	friend class PIIntrospectionServer;
@@ -75,11 +100,23 @@ public:
 	__PIINTROSPECTION_SINGLETON_H__(Containers)

 	// clang-format off
+	//! \~english Notify about new container allocation
+	//! \~russian Уведомить о новом выделении контейнера
 	void containerNew   (const PIIntrospectionContainersType & ti, uint isz);
+	//! \~english Notify about container deletion
+	//! \~russian Уведомить об удалении контейнера
 	void containerDelete(const PIIntrospectionContainersType & ti);
+	//! \~english Notify about container memory allocation
+	//! \~russian Уведомить о выделении памяти контейнером
 	void containerAlloc (const PIIntrospectionContainersType & ti, ullong cnt);
+	//! \~english Notify about container memory freeing
+	//! \~russian Уведомить об освобождении памяти контейнером
 	void containerFree  (const PIIntrospectionContainersType & ti, ullong cnt);
+	//! \~english Notify about container memory usage
+	//! \~russian Уведомить об использовании памяти контейнером
 	void containerUsed  (const PIIntrospectionContainersType & ti, ullong cnt);
+	//! \~english Notify about container unused memory
+	//! \~russian Уведомить о неиспользуемой памяти контейнера
 	void containerUnused(const PIIntrospectionContainersType & ti, ullong cnt);
 	// clang-format on

@@ -91,14 +128,15 @@ private:
 };


-#else
-#  define PIINTROSPECTION_CONTAINER_NEW(t, isz)
-#  define PIINTROSPECTION_CONTAINER_DELETE(t)
-#  define PIINTROSPECTION_CONTAINER_ALLOC(t, cnt)
-#  define PIINTROSPECTION_CONTAINER_FREE(t, cnt)
-#  define PIINTROSPECTION_CONTAINER_USED(t, cnt)
-#  define PIINTROSPECTION_CONTAINER_UNUSED(t, cnt)
-#endif
+#  else
+#	define PIINTROSPECTION_CONTAINER_NEW(t, isz)
+#	define PIINTROSPECTION_CONTAINER_DELETE(t)
+#	define PIINTROSPECTION_CONTAINER_ALLOC(t, cnt)
+#	define PIINTROSPECTION_CONTAINER_FREE(t, cnt)
+#	define PIINTROSPECTION_CONTAINER_USED(t, cnt)
+#	define PIINTROSPECTION_CONTAINER_UNUSED(t, cnt)
+#  endif // defined(PIP_INTROSPECTION) && !defined(PIP_FORCE_NO_PIINTROSPECTION)


 #endif // PIINTROSPECTION_CONTAINERS_H
+//! \}
--- a/libs/main/introspection/piintrospection_server.h
+++ b/libs/main/introspection/piintrospection_server.h
@@ -51,13 +51,23 @@ class PISystemMonitor;
 #	define PIINTROSPECTION_START(name) PIINTROSPECTION_SERVER->start(#name);
 #	define PIINTROSPECTION_STOP        PIINTROSPECTION_SERVER->stop();

+//! \~english Introspection server class for collecting and broadcasting PIP internal statistics
+//! \~russian Класс сервера интроспекции для сбора и распространения внутренних статистик PIP
 class PIP_EXPORT PIIntrospectionServer: public PIPeer {
 	PIOBJECT_SUBCLASS(PIIntrospectionServer, PIPeer);

 public:
+	//! \~english Get singleton instance of introspection server
+	//! \~russian Получить синглтон-экземпляр сервера интроспекции
 	static PIIntrospectionServer * instance();

+	//! \~english Start introspection server with specified name
+	//! \~russian Запустить сервер интроспекции с указанным именем
+	//! \param server_name \~english Name of the server to start \~russian Имя сервера для запуска
 	void start(const PIString & server_name);
+
+	//! \~english Stop introspection server
+	//! \~russian Остановить сервер интроспекции
 	void stop();

 private:
--- a/libs/main/introspection/piintrospection_threads.h
+++ b/libs/main/introspection/piintrospection_threads.h
@@ -17,25 +17,39 @@
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

+//! \addtogroup Introspection
+//! \{
+//! \file piintrospection_threads.h
+//! \brief Thread introspection interface
+//! \~english Interface for thread introspection and monitoring
+//! \~russian Интерфейс для интроспекции и мониторинга потоков
+//! \details
+//! \~english Provides callbacks for thread lifecycle events such as creation, deletion, start, run, wait, stop and completion
+//! \~russian Предоставляет обратные вызовы для событий жизненного цикла потоков: создание, удаление, запуск, выполнение, ожидание,
+//! остановка и завершение
+//! \}
+
 #ifndef PIINTROSPECTION_THREADS_H
-#define PIINTROSPECTION_THREADS_H
+#  define PIINTROSPECTION_THREADS_H

-#if defined(PIP_INTROSPECTION) && !defined(PIP_FORCE_NO_PIINTROSPECTION)
+#  if defined(PIP_INTROSPECTION) && !defined(PIP_FORCE_NO_PIINTROSPECTION)

-#  include "piintrospection_base.h"
+#	include "piintrospection_base.h"

 class PIIntrospectionThreads;

-#  define PIINTROSPECTION_THREADS                (PIIntrospectionThreadsInterface::instance())
+#	define PIINTROSPECTION_THREADS                (PIIntrospectionThreadsInterface::instance())

-#  define PIINTROSPECTION_THREAD_NEW(t)          PIINTROSPECTION_THREADS->threadNew(t);
-#  define PIINTROSPECTION_THREAD_DELETE(t)       PIINTROSPECTION_THREADS->threadDelete(t);
-#  define PIINTROSPECTION_THREAD_START(t)        PIINTROSPECTION_THREADS->threadStart(t);
-#  define PIINTROSPECTION_THREAD_RUN(t)          PIINTROSPECTION_THREADS->threadRun(t);
-#  define PIINTROSPECTION_THREAD_WAIT(t)         PIINTROSPECTION_THREADS->threadWait(t);
-#  define PIINTROSPECTION_THREAD_STOP(t)         PIINTROSPECTION_THREADS->threadStop(t);
-#  define PIINTROSPECTION_THREAD_RUN_DONE(t, us) PIINTROSPECTION_THREADS->threadRunDone(t, us);
+#	define PIINTROSPECTION_THREAD_NEW(t)          PIINTROSPECTION_THREADS->threadNew(t);
+#	define PIINTROSPECTION_THREAD_DELETE(t)       PIINTROSPECTION_THREADS->threadDelete(t);
+#	define PIINTROSPECTION_THREAD_START(t)        PIINTROSPECTION_THREADS->threadStart(t);
+#	define PIINTROSPECTION_THREAD_RUN(t)          PIINTROSPECTION_THREADS->threadRun(t);
+#	define PIINTROSPECTION_THREAD_WAIT(t)         PIINTROSPECTION_THREADS->threadWait(t);
+#	define PIINTROSPECTION_THREAD_STOP(t)         PIINTROSPECTION_THREADS->threadStop(t);
+#	define PIINTROSPECTION_THREAD_RUN_DONE(t, us) PIINTROSPECTION_THREADS->threadRunDone(t, us);

+//! \~english Thread introspection interface class
+//! \~russian Класс интерфейса интроспекции потоков
 class PIP_EXPORT PIIntrospectionThreadsInterface {
 	friend class PIIntrospection;

@@ -43,12 +57,26 @@ public:
 	__PIINTROSPECTION_SINGLETON_H__(Threads)

 	// clang-format off
+	//! \~english Called when new thread is created
+	//! \~russian Вызывается при создании нового потока
 	void threadNew    (PIThread * t);
+	//! \~english Called when thread is deleted
+	//! \~russian Вызывается при удалении потока
 	void threadDelete (PIThread * t);
+	//! \~english Called when thread is starting
+	//! \~russian Вызывается при запуске потока
 	void threadStart  (PIThread * t);
+	//! \~english Called when thread starts execution
+	//! \~russian Вызывается при начале выполнения потока
 	void threadRun    (PIThread * t);
+	//! \~english Called when thread is waiting
+	//! \~russian Вызывается при ожидании потока
 	void threadWait   (PIThread * t);
+	//! \~english Called when thread is stopped
+	//! \~russian Вызывается при остановке потока
 	void threadStop   (PIThread * t);
+	//! \~english Called when thread execution is done
+	//! \~russian Вызывается при завершении выполнения потока
 	void threadRunDone(PIThread * t, ullong us);
 	// clang-format on

@@ -59,14 +87,15 @@ private:
 	PIIntrospectionThreads * p;
 };

-#else
-#  define PIINTROSPECTION_THREAD_NEW(t)
-#  define PIINTROSPECTION_THREAD_DELETE(t)
-#  define PIINTROSPECTION_THREAD_START(t)
-#  define PIINTROSPECTION_THREAD_RUN(t)
-#  define PIINTROSPECTION_THREAD_WAIT(t)
-#  define PIINTROSPECTION_THREAD_STOP(t)
-#  define PIINTROSPECTION_THREAD_RUN_DONE(t, us)
-#endif
+#  else
+#	define PIINTROSPECTION_THREAD_NEW(t)
+#	define PIINTROSPECTION_THREAD_DELETE(t)
+#	define PIINTROSPECTION_THREAD_START(t)
+#	define PIINTROSPECTION_THREAD_RUN(t)
+#	define PIINTROSPECTION_THREAD_WAIT(t)
+#	define PIINTROSPECTION_THREAD_STOP(t)
+#	define PIINTROSPECTION_THREAD_RUN_DONE(t, us)
+#  endif

 #endif // PIINTROSPECTION_THREADS_H
+//! \}