Документирование перечислимых флагов с помощью 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, что мне и нужно.
Решение
Так что сделайте тип аргумента Options, Вы можете написать перегруженные операторы, которые возвращают Options обрабатывать & а также | и любые другие логические операторы, которые вам нужны.
Другие решения
Документирование переменной с именем 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 */}