SHS/pip
4
3
Fork 0
Code Issues 67 Pull Requests 1 Actions Releases Wiki Activity
Files
42a1507536682986e721e2249e74a0b35f1150c9
pip/plans/doxygen_docs.md
andrey.bychkov 6557933a2e doxygen docs plan
2026-02-26 22:58:47 +03:00

338 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# План: Добавление документации 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
Reference in New Issue View Git Blame Copy Permalink