pip/plans/doxygen_docs.md

План: Добавление документации 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. Проверить, что файл компилируется после изменений