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