Документирующий препроцессор определяет в Doxygen

Question

Возможно ли, чтобы документ препроцессора определялся в Doxygen? Я ожидал, что смогу сделать это просто как переменная или функция, однако выход Doxygen, похоже, «потерял» документацию для определения и не содержит самого определения.

Я попытался следующие

/**My Preprocessor Macro.*/ 
#define TEST_DEFINE(x) (x*x) 

и

/**@def TEST_DEFINE 

    My Preprocessor Macro. 
*/ 
#define TEST_DEFINE(x) (x*x) 

Я также попытался положить их в группе (пытался defgroup, addtogroup и внутригрупповой), а не только в «области файла», однако, что также не имели никакого эффекта (хотя другие элементы в группе были задокументированы по назначению).

Я просмотрел различные варианты Doxygen, но не мог видеть ничего, что могло бы (или предотвратить) документацию определений.

Answer 1

Да, это возможно. Doxygen documentation говорит:

Документально глобальные объекты (функции, определения типов, перечислений, макросы и т.д.), необходимо документировать файл, в котором они определены. Другими словами, должно быть по крайней мере

/*! \file */

или

/** @file */

строка в этом файле.

Вы можете использовать @defgroup, @addtogroup и @ingroup положить связанные элементы в том же модуле, даже если они появляются в отдельных файлах (см документацию here для деталей). Вот минимальный пример, который работает для меня (с использованием Doxygen 1.6.3):

Doxyfile:

# Empty file. 

test.h:

/** @file */ 

/**My Preprocessor Macro.*/ 
#define TEST_DEFINE(x) (x*x) 

/** 
* @defgroup TEST_GROUP Test Group 
* 
* @{ 
*/ 

/** Test AAA documentation. */ 
#define TEST_AAA (1) 
/** Test BBB documentation. */ 
#define TEST_BBB (2) 
/** Test CCC documentation. */ 
#define TEST_CCC (3) 
/** @} */ 

foo.h:

/** @file */ 

/** 
* @addtogroup TEST_GROUP 
* 
* @{ 
*/ 

/** @brief My Class. */  
class Foo { 
    public: 
     void method(); 
}; 

/** @} */ 

bar.h:

/** @file */ 

/** 
* @ingroup TEST_GROUP 
* My Function. 
*/ 
void Bar(); 

В этом случае документация TEST_DEFINE появляется в Test.ч записи под вкладки файлов в выводе HTML и определение в TEST_AAA и т.д. появляется под Test Group в модулях вкладки вместе с классом Foo и функциями Bar.

Одна вещь, чтобы отметить, что если вы поставите имя файла после @file команды, например:

/** @file Test.h */ 

, то это должно совпадать с фактическим именем файла. Если это не так, документация для элементов в файле не будет сгенерирована.

Альтернативное решение, если вы не хотите добавлять команды @file, состоит в том, чтобы установить EXTRACT_ALL = YES в ваш Doxyfile.

Надеюсь, это поможет!

Answer 2

Попробуйте установить параметр EXTRACT_ALL, у меня есть этот набор в моем проекте и он создает документацию для #defines. Там может быть более элегантный способ сделать это без использования EXTRACT_ALL, поэтому обязательно проверять документацию

http://www.doxygen.nl/config.html#cfg_extract_all

Answer 3

В моих файлах «C», я использую комментарий формат и #define строку:

/** @brief Number of milli-seconds to wait*/ 
#define kTimeoutMSec (2) 

Мои HTML документы должны в конечном итоге, содержащий документацию на указанный мной. (У меня есть @file в верхней части файла и EXTRACT_ALL = YES)

Answer 4

Добавляя к предыдущим ответам, также необходимо иметь ENABLE_PREPROCESSING=YES на Doxyfile.