Comment commenter le fichier lui-même en utilisant Javadoc et Doxygen

Question

J'ai un problème avec la documentation du fichier lui-même en utilisant le style javadoc et doxygen. Je peux générer une belle documentation pour les variables et les fonctions mais pour le fichier lui-même, le doxygen pense toujours que l'en-tête du fichier est la documentation de la prochaine variable immédiate ou de la macro suivante même si cette var ou macro a son propre bloc de commentaire javadoc. Prenons l'exemple ci-dessous:

/** 
* 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 

Alors, quand je produis des documents pour ce fichier (en utilisant doxygen/doxywizard) la documentation de la macro définie sera remplacée par l'en-tête du fichier.

Quelle est la bonne façon de faire une telle chose? Est-il considéré comme une bonne pratique de documenter le fichier lui-même (avec des informations telles que la description, l'auteur, l'heure, la version et ...) et si oui, comment résoudre le problème que je viens de décrire?

Answer 1

Utilisez la commande \file.

Le manuel fournit Doxygen ce code exemple:

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

et link to the output: