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

11 KiB
Raw Blame History

План: Добавление документации Doxygen в заголовочные файлы PIP

Обзор

Необходимо добавить базовую документацию Doxygen (\brief) во все публичные заголовочные файлы проекта. Каждый файл должен содержать:

  • Документацию в начале файла (\file, \brief, группа)
  • Документацию для каждого класса (\class, \brief)
  • Документацию для всех публичных методов (\brief)

Стиль документации

Используется два стиля комментариев (оба поддерживаются):

  1. //! - однострочные комментарии (предпочтительно)
  2. /*! ... */ - многострочные блоки

Пример оформления (на основе pipair.h)

//! \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. Добавить документацию в начале файла (если отсутствует):

    //! \addtogroup <GroupName>
//! \{
//! \file <filename>
//! \brief
//! \~english Brief description
//! \~russian Краткое описание
//! \~\}

  3. Добавить документацию для каждого класса:

    //! \class ClassName
//! \brief
//! \~english Class description
//! \~russian Описание класса

  4. Добавить документацию для методов:

    //! \~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