Как прокомментировать сам файл, используя Javadoc и Doxygen

Question

У меня проблема с документированием самого файла с использованием стиля javadoc и doxygen. Я могу сгенерировать хорошую документацию для переменных и функций, но для самого файла doxygen всегда думает, что заголовок файла является документацией для следующей непосредственной переменной или макроса, следующего за ним, даже если этот var или макрос имеет свой собственный блок комментариев javadoc. Возьмите пример ниже:

/**
 * MAX9611 Sensor I2C
 *
 * @author  Saeid Yazdani
 * @date    01/07/2016
 *
 */


#ifndef MAX9611_HPP
#define MAX9611_HPP

#include "stdint.h" //for uint and stuff

/**
* max9611 RS+ ADC value is 0 to 57.3V in 12bit
* so to convert it to real voltage we need this constant 57.3/4096
* this can be used for both RS+ and OUT adc values to be converted to real V
*/
#define MAX9611_VOLT_MUL        0.0139892578125

Поэтому, когда я создаю документацию для этого файла (используя doxygen / doxywizard), документация для определенного макроса будет заменена заголовком файла.

Как правильно сделать такую ​​вещь? Считается ли хорошей практикой документировать сам файл (с информацией, такой как описание, автор, время, версия и...), и если да, то как решить проблему, которую я только что описал?

Answer 1

Использовать \file команда.

Руководство Doxygen предоставляет этот пример кода:

/** \file file.h
 * A brief file description.
 * A more elaborated file description.
 */
/**
 * A global integer value.
 * More details about this value.
 */
extern int globalValue;

и ссылка на вывод: