Документирование перечислимых флагов с помощью Doxygen или аналогичных

Question

Документирование перечислимых флагов с помощью Doxygen или аналогичных

Я только что добавил Doxygen к моему набору инструментов, и хотя я знаком с большинством техник, я немного запутался в том, как мне следует документировать флаги enum (также применимо к документации в целом, с или без Doxygen). Учитывая следующий класс:

class foo
{
/// @enum  Options
/// @brief Specifies options for the object. Options are combined using
///        the bitwise OR operator e.g. "OPTION1 | OPTION2".
enum Options
{
OPTION1 = 1, //< Option 1 description.
OPTION2 = 2, //< Option 2 description.
OPTION3 = 4  //< Option 3 description.
};

/// @brief Does something.
/// @param options  Specifies options.
void bar(int options) {/* Do something */}
};

Как мне указать пользователю, как использовать параметр options функции bar? Параметр имеет тип int, а не Options, поэтому нет прямой связи между параметром и перечислением. Если бы параметр имел тип Options, то в документации была бы ссылка на описание enum, что мне и нужно.

0

c++documentation doxygen enums flags

Решение

Другие решения

Документирование переменной с именем options с «Определяет параметры» не является значимым комментарием. Имя переменной уже говорит то, что говорит ваш существующий комментарий. Так что сделайте ваш комментарий значимым:

/// @brief Does something.
/// @param options  Specifies options for the object, which must be a bitwise OR
///                 of zero or more of the bit flags in enum foo::Options.
void bar(int options) {/* Do something */}

1

Источник

Accepted Answer

Так что сделайте тип аргумента Options, Вы можете написать перегруженные операторы, которые возвращают Options обрабатывать & а также | и любые другие логические операторы, которые вам нужны.

2