From 6557933a2ef5d89ebf0b8f72064267323b8e96a3 Mon Sep 17 00:00:00 2001
From: "andrey.bychkov" <andrey@signalmodelling.ru>
Date: Thu, 26 Feb 2026 22:58:47 +0300
Subject: [PATCH] doxygen docs plan

---
 plans/doxygen_docs.md | 337 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 337 insertions(+)
 create mode 100644 plans/doxygen_docs.md

diff --git a/plans/doxygen_docs.md b/plans/doxygen_docs.md
new file mode 100644
index 00000000..771e2f43
--- /dev/null
+++ b/plans/doxygen_docs.md
@@ -0,0 +1,337 @@
+# План: Добавление документации Doxygen в заголовочные файлы PIP
+
+## Обзор
+
+Необходимо добавить базовую документацию Doxygen (`\brief`) во все публичные заголовочные файлы проекта. Каждый файл должен содержать:
+- Документацию в начале файла (`\file`, `\brief`, группа)
+- Документацию для каждого класса (`\class`, `\brief`)
+- Документацию для всех публичных методов (`\brief`)
+
+## Стиль документации
+
+Используется два стиля комментариев (оба поддерживаются):
+1. `//!` - однострочные комментарии (предпочтительно)
+2. `/*! ... */` - многострочные блоки
+
+## Пример оформления (на основе pipair.h)
+
+```cpp
+//! \addtogroup Containers
+//! \{
+//! \file pipair.h
+//! \brief
+//! \~english Declares \a PIPair
+//! \~russian Объявление \a PIPair
+//! \~\authors
+//! \~english Ivan Pelipenko peri4ko@yandex.ru; Andrey Bychkov work.a.b@yandex.ru
+//! \~russian Иван Пелипенко peri4ko@yandex.ru; Андрей Бычков work.a.b@yandex.ru
+//! \~\}
+/*
+    Лицензия GPL
+*/
+
+#ifndef PIPAIR_H
+#define PIPAIR_H
+
+#include "picout.h"
+
+//! \addtogroup Containers
+//! \{
+//! \class PIPair
+//! \brief
+//! \~english Class template that provides a way to store two heterogeneous objects as a single unit.
+//! \~russian Класс, который позволяет хранить два разнородных объекта как единое целое.
+//! \~\}
+//! \~\sa \a PIMap
+template<typename Type0, typename Type1>
+class PIPair {
+public:
+    //! \~english Constructs an empty PIPair.
+    //! \~russian Создает пустой PIPair.
+    PIPair(): first(), second() {}
+
+    //! \~english Constructs PIPair from values `value0` and `value1`.
+    //! \~russian Создает PIPair из `value0` и `value1`.
+    PIPair(const Type0 & value0, const Type1 & value1) {
+        first  = value0;
+        second = value1;
+    }
+
+    //! \~english First element.
+    //! \~russian Первый элемент.
+    Type0 first;
+
+    //! \~english Second element.
+    //! \~russian Второй элемент.
+    Type1 second;
+};
+
+//! \~english Compare operator with PIPair.
+//! \~russian Оператор сравнения с PIPair.
+template<typename Type0, typename Type1>
+inline bool operator==(const PIPair<Type0, Type1> & value0, const PIPair<Type0, Type1> & value1) {
+    return (value0.first == value1.first) && (value0.second == value1.second);
+}
+
+#endif // PIPAIR_H
+```
+
+## Инструкции для агента (на один файл)
+
+1. **Прочитать файл** и определить:
+   - Группу модуля (Container, Types, Core, IO, Thread, Math и т.д.)
+   - Все классы в файле
+   - Все публичные методы каждого класса
+   - Все свободные функции (non-member)
+
+2. **Добавить документацию в начале файла** (если отсутствует):
+   ```cpp
+   //! \addtogroup <GroupName>
+   //! \{
+   //! \file <filename>
+   //! \brief
+   //! \~english Brief description
+   //! \~russian Краткое описание
+   //! \~\}
+   ```
+
+3. **Добавить документацию для каждого класса**:
+   ```cpp
+   //! \class ClassName
+   //! \brief
+   //! \~english Class description
+   //! \~russian Описание класса
+   ```
+
+4. **Добавить документацию для методов**:
+   ```cpp
+   //! \~english Method description.
+   //! \~russian Описание метода.
+   ReturnType methodName(params);
+   ```
+
+5. **Проверить, что файл компилируется** после изменений
+
+## Список файлов для обработки
+
+### Containers (11 файлов)
+- libs/main/containers/picollections.h
+- libs/main/containers/picontainersmodule.h
+- libs/main/containers/pideque.h
+- libs/main/containers/pimap.h
+- libs/main/containers/pipair.h
+- libs/main/containers/piqueue.h
+- libs/main/containers/piset.h
+- libs/main/containers/pistack.h
+- libs/main/containers/pivector.h
+- libs/main/containers/pivector2d.h
+
+### Core (11 файлов)
+- libs/main/core/pibase.h
+- libs/main/core/pibase_macros.h
+- libs/main/core/picoremodule.h
+- libs/main/core/picout.h
+- libs/main/core/piincludes.h
+- libs/main/core/piincludes_p.h
+- libs/main/core/piinit.h
+- libs/main/core/pimemoryblock.h
+- libs/main/core/piobject.h
+- libs/main/core/piobject_macros.h
+- libs/main/core/piwaitevent_p.h
+
+### Types (17 файлов)
+- libs/main/types/pibitarray.h
+- libs/main/types/pibytearray.h
+- libs/main/types/pidatetime.h
+- libs/main/types/piflags.h
+- libs/main/types/pinetworkaddress.h
+- libs/main/types/pipropertystorage.h
+- libs/main/types/pisystemtime.h
+- libs/main/types/pitime.h
+- libs/main/types/pitypesmodule.h
+- libs/main/types/pivaluetree.h
+- libs/main/types/pivariant.h
+- libs/main/types/pivarianttypes.h
+- libs/main/types/pivariantsimple.h
+- libs/main/types/pinetworkaddress.h
+- libs/main/types/colors_p.h
+- libs/main/types/pipropertystorage.h
+
+### Text (7 файлов)
+- libs/main/text/pichar.h
+- libs/main/text/piconstchars.h
+- libs/main/text/piregularexpression.h
+- libs/main/text/pistring.h
+- libs/main/text/pistringlist.h
+- libs/main/text/pitextmodule.h
+- libs/main/text/pitextstream.h
+
+### IO Devices (20+ файлов)
+- libs/main/io_devices/pibinarylog.h
+- libs/main/io_devices/pican.h
+- libs/main/io_devices/piconfig.h
+- libs/main/io_devices/pidir.h
+- libs/main/io_devices/piethernet.h
+- libs/main/io_devices/pifile.h
+- libs/main/io_devices/pigpio.h
+- libs/main/io_devices/piiobytearray.h
+- libs/main/io_devices/piiodevice.h
+- libs/main/io_devices/piiodevicesmodule.h
+- libs/main/io_devices/piiostream.h
+- libs/main/io_devices/piiostring.h
+- libs/main/io_devicespipeer.h
+- libs/main/io_devices/piserial.h
+- libs/main/io_devices/pisharedmemory.h
+- libs/main/io_devices/pispi.h
+- libs/main/io_devices/pitransparentdevice.h
+- libs/main/io_devices/piusb.h
+
+### Thread (18 файлов)
+- libs/main/thread/piblockingqueue.h
+- libs/main/thread/piconditionvar.h
+- libs/main/thread/pigrabberbase.h
+- libs/main/thread/pimutex.h
+- libs/main/thread/pipipelinethread.h
+- libs/main/thread/piprotectedvariable.h
+- libs/main/thread/pireadwritelock.h
+- libs/main/thread/pisemaphore.h
+- libs/main/thread/pispinlock.h
+- libs/main/thread/pithread.h
+- libs/main/thread/pithreadmodule.h
+- libs/main/thread/pithreadnotifier.h
+- libs/main/thread/pithreadpoolloop.h
+- libs/main/thread/pithreadpoolexecutor.h
+- libs/main/thread/pitimer.h
+
+### Math (14 файлов)
+- libs/main/math/picrc.h
+- libs/main/math/pievaluator.h
+- libs/main/math/pifft.h
+- libs/main/math/pigeometry.h
+- libs/main/math/piline.h
+- libs/main/math/pimatcomplex.h
+- libs/main/math/pimatvector.h
+- libs/main/math/pimatmatrix.h
+- libs/main/math/pimathsolver.h
+- libs/main/math/pimathbase.h
+- libs/main/math/pimathmodule.h
+- libs/main/math/piquantaternion.h
+- libs/main/math/pirect.h
+- libs/main/math/pistatistic.h
+
+### Crypt (3 файла)
+- libs/main/crypt/piauth.h
+- libs/main/crypt/picrypt.h
+- libs/main/crypt/picryptmodule.h
+
+### Digest (1 файл)
+- libs/main/digest/pidigest.h
+
+### Serialization (7 файлов)
+- libs/main/serialization/pibinarystream.h
+- libs/main/serialization/pichunkstream.h
+- libs/main/serialization/pijson.h
+- libs/main/serialization/pijsonserialization.h
+- libs/main/serialization/piserializationmodule.h
+- libs/main/serialization/pivaluetree_conversions.h
+- libs/main/serialization/pijson.h
+
+### HTTP (6 файлов)
+- libs/main/http_client/pihttpclient.h
+- libs/main/http_client/pihttpclientmodule.h
+- libs/main/http_server/pihttpserver.h
+- libs/main/http_server/pihttpservermodule.h
+- libs/main/http_server/microhttpd_server.h
+- libs/main/http_common/pihttptypes.h
+
+### State Machine (4 файла)
+- libs/main/state_machine/pistatemachinebase.h
+- libs/main/state_machine/pistatemachinestate.h
+- libs/main/state_machine/pistatemachinetransition.h
+- libs/main/state_machine/pistatemachinemodule.h
+
+### System (11 файлов)
+- libs/main/system/pihidevice.h
+- libs/main/system/pilibrary.h
+- libs/main/system/piprocess.h
+- libs/main/system/piplugin.h
+- libs/main/system/pisignals.h
+- libs/main/system/pisysteminfo.h
+- libs/main/system/pisystemmodule.h
+- libs/main/system/pisystemtests.h
+
+### Cloud (5 файлов)
+- libs/main/cloud/picloudbase.h
+- libs/main/cloud/picloudclient.h
+- libs/main/cloud/picloudmodule.h
+- libs/main/cloud/picloudserver.h
+- libs/main/cloud/picloudtcp.h
+
+### Client/Server (4 файла)
+- libs/main/client_server/piclientserver_client.h
+- libs/main/client_server/piclientserver_client_base.h
+- libs/main/client_server/piclientserver_module.h
+- libs/main/client_server/piclientserver_server.h
+
+### Console (9 файлов)
+- libs/main/console/piconsolemodule.h
+- libs/main/console/pikbdlistener.h
+- libs/main/console/piscreen.h
+- libs/main/console/piscreenconsole.h
+- libs/main/console/piscreendrawer.h
+- libs/main/console/piscreentile.h
+- libs/main/console/piscreentiles.h
+- libs/main/console/piscreentypes.h
+- libs/main/console/piterminal.h
+
+### Resources (3 файла)
+- libs/main/resources/piresources.h
+- libs/main/resources/piresourcesstorage.h
+
+### Application (3 файла)
+- libs/main/application/piapplication.h
+- libs/main/application/pimain.h
+
+### Literals (6 файлов)
+- libs/main/literals/piliterals.h
+- libs/main/literals/piliterals_bytearray.h
+- libs/main/literals/piliterals_bytes.h
+- libs/main/literals/piliterals_regularexpression.h
+- libs/main/literals/piliterals_string.h
+- libs/main/literals/piliterals_time.h
+
+### Geo (4 файла)
+- libs/main/geo/piellipsoidmodel.h
+- libs/main/geo/pigeomodule.h
+- libs/main/geo/pigeoposition.h
+
+### Units (много файлов)
+- libs/main/units/piunits.h
+- libs/main/units/piunits_base.h
+- libs/main/units/piunits_class_angle.h
+- libs/main/units/piunits_class_distance.h
+- libs/main/units/piunits_class_information.h
+- libs/main/units/piunits_class_mass.h
+- libs/main/units/piunits_class_pressure.h
+- libs/main/units/piunits_class_temperature.h
+- libs/main/units/piunits_class_time.h
+- libs/main/units/piunits_prefix.h
+- libs/main/units/piunits_value.h
+
+### Code (3 файла)
+- libs/main/code/picodeparser.h
+- libs/main/code/picodeinfo.h
+- libs/main/code/picodemodule.h
+
+### Compression (1 файл)
+- libs/main/compress/picompress.h
+
+### OpenCL (1 файл)
+- libs/main/opencl/piopencl.h
+
+### Другие модули
+- libs/main/pip.h
+- libs/main/piplatform.h
+- libs/main/literals/piliterals.h
+- libs/main/code/picodeparser.h
+- libs/main/cloud/picloudtcp.h