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

Можно ли документировать препроцессор в 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 и ingroup), а не только в "область файлов", однако это не имело никакого эффекта (хотя другие элементы в группе были задокументированы по назначению).

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

Ответ 1

Да, это возможно. Документация Doxygen гласит:

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

/*! \file */

или

/** @file */

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

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

Доксифайл:

# 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.h на вкладке " Файлы " в выводе HTML, а определения TEST_AAA и т.д. Появляются в разделе " Группа тестирования" на вкладке " Модули " вместе с классом Foo и функцией Bar.

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

/** @file Test.h */

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

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

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

Ответ 2

В моих файлах "C" я использую формат комментария и строку #define следующим образом:

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

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

Ответ 3

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

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

Ответ 4

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