Doxygen注释使用中应该注意的问题.docVIP

1. 没有内容的注释 1 2. 位于代码右侧的注释 1 3. 一组函数，#define的注释 1 4. 多行注释的分行问题 2 5. 隐藏私有与保护方法与属性 2 6. 隐藏其他内容 2 Doxygen注释使用中应该注意的问题 1. 没有内容的注释 /** * @file DataProxy.h * @brief core数据代理适配层 * @sa 参考对象 * @author zhangzewu * @date 19/11/2012 * 详细描述 */ 问题：因为没有内容，上例标红的注释应该删除。 位于代码右侧的注释 BOOL TagUnderLine(std::string str, const char* pszText, bool bFlag);///下划线 问题：上例中标红的注释应为///下划线,否则会被当做下面代码的注释。 一组函数，#define的注释 ///参数类型，与value的类型相对应 #define DVTS_int \x01 #define DVTS_float \x02 #define DVTS_string \x03 #define DVTS_indicator \x04 #define DVTS_matrix \x05 #define DVTS_dzhobj \x06 问题：上例中的注释是对这组#define的注释，但在Doxygen生成的文档中只会出现在第一个#define下面，其他#define都会没有注释。应将这组#define分组，然后将注释放在组名的下面。 /**@name #define-1（组名） * 参数类型，与value的类型相对应（整个组的注释） */ //@{ #define DVTS_int \x01 #define DVTS_float \x02 #define DVTS_string \x03 #define DVTS_indicator \x04 #define DVTS_matrix \x05 #define DVTS_dzhobj \x06 //@} 多行注释的分行问题 ///包信息 ///第0、1位表示事务的状态信息：1-开始; 2-持续中; 3-结束 ///第2位表示消息是同步还是异步: 0-同步; 1-异步 ///第3位表示消息是函数还是命令: 0-函数; 1-命令 ///第4位表示消息是否执行成功: 0-执行成功; 1-执行失败。仅仅在返回值是有效 问题：上例的注释在生成的文档中会一行显示，不易理解，应用BR将注释分行： /** 包信息 * BR第0、1位表示事务的状态信息：1-开始; 2-持续中; 3-结束 * BR第2位表示消息是同步还是异步: 0-同步; 1-异步 * BR第3位表示消息是函数还是命令: 0-函数; 1-命令 * 第4位表示消息是否执行成功: 0-执行成功; 1-执行失败。仅仅在返回值是有效 */ 5. 隐藏私有与保护方法与属性 不在生成文档中显示私有方法与属性，只要在Expert-Build里面勾选EXTRACT_ALL，并不勾选EXTRACT_PRIVATE. 不在生成文档中显示保护方法与属性，需要在不显示私有方法与属性的基础上，在所有“protected：”关键字后加上@privatesection命令： protected: /**@privatesection */ 6. 隐藏其他内容 需要隐藏其他内容，可以在要隐藏的内容前后加上@cond与@endcond命令，如： ///@cond typedef struct { size_t start; int step; /// 可以0 size_t end; /// 值的个数 inline size_t Count() const { return int(end-start)/step + 1; } /// 位置计算，错误返回0xffffffff inline size_t Index(size_t v) const { return (v-start)%step==0 ? (v-start)/step : 0xffffffff; } } Range; ///@endcond