如何使用 Javadoc 和 Doxygen 注释文件本身答案

【问题标题】：How to comment the file itself using Javadoc and Doxygen如何使用 Javadoc 和 Doxygen 注释文件本身
【发布时间】：2016-12-01 07:00:07
【问题描述】：

我在使用 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），定义的宏的文档将被文件头替换。

做这种事情的正确方法是什么？记录文件本身（包括描述、作者、时间、版本等信息）是否被认为是一种好习惯？如果是，如何解决我刚才描述的问题？

【问题讨论】：

你看过\file命令了吗？
@albert 谢谢，你是对的。也许您想将其发布为答案？

标签： documentation javadoc doxygen doxywizard

【解决方案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;

还有一个link to the output：

【讨论】：