PIVector2D - add funcs, optimize, tests, fixes, doxygen #194
337
plans/doxygen_docs.md
Normal file
337
plans/doxygen_docs.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user