Wie Sie die Datei selbst mit Javadoc und Doxygen kommentieren

Question

Ich habe ein Problem mit der Dokumentation der Datei selbst mit Javadoc-Stil und Doxygen. Ich kann nette Dokumentation für Variablen und Funktionen generieren, aber für die Datei selbst denkt der doxygen immer, dass der Header der Datei die Dokumentation für die nächste unmittelbare Variable oder das folgende Makro ist, selbst wenn diese var oder dieses Makro einen eigenen Javadoc-Kommentarblock hat. Nehmen Sie das folgende Beispiel:

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

Also, wenn ich die Dokumentation für diese Datei (mit doxygen/doxywizard) die Dokumentation für das definierte Makro generieren wird durch den Header der Datei ersetzt werden.

Was ist der richtige Weg, um so etwas zu tun? Ist es eine gute Vorgehensweise, die Datei selbst zu dokumentieren (mit Informationen wie Beschreibung, Autor, Zeit, Version und ...) und wenn ja, wie kann ich das Problem, das ich gerade beschrieben habe, lösen?

Answer 1

Verwenden Sie den Befehl \file.

Die Doxygen Handbuch bietet dieses Beispielcode:

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

und link to the output: