Doxygen编写流程

流程

1、核对源注释，检查语义是否仍正确，修改用object-c代码写的注释。
2、添加原来没有的注释
3、生成doxygen 文档，检查格式是否正确，修改不正确的地方。
4、对于未实现的函数，保留注释，不出现在文档。

例子

1、对 实现文件使用C/C++注释，要求 写明主要的流程、算法 ，注释符后要留 一个空格 。
2、头文件使用Docxygen风格编写注释,要求写明使用方法，注意要点,

• doxygen是一套由代码自动生成HTML文档的工具，被boost, CppUnit, ACE, KDE, QT等知名的大型项目所使用.
• 使用doxygen可以减少项目开发过程产生的"中间产物", 使整个开发更为"轻量化", 而且相比于写一份WORD或WIKI文档, 程序员更喜欢在代码里敲注释行.

以下为常用格式

文件头

• 如果头文件只有一个类，则不需要头文件注释，直接写类注释就可以了； 如果头文件是C的头文件或有多个类声明，则需要写头文件注释。

1 /** 2 @file 3 @author WangZhe 4 @brief  每个多任务操作系统都有一些功能,属于操作系统原理级别的东西。5 */ 

注意@符号后面的doxygen关键字,

• @file 表示文件名, 这个不写, 会自动生成。
• @author 作者。
• @brief 摘要。
• 注意第一行的/**, 这个标记才能让该段注释被doxygen识别。

类的说明

 1 /**  2 @class CLock  3 @author Walzer  4 @ingroup OS_ADAPTOR  5 @brief 定义域自释放锁。 6 @warning 在CLock生命期中, 不要将传入的CCriticalSection对象析构, 否则会造成不可知后果。 7 @code 8     // sample code      9     OS::CCriticalSection g_cs;         10     void func1()     11     {    12          OS::CLock(&g_cs);13          // do your job     14     }15 16     void func2()     17     {     18         g_cs.Lock();         19         // do your job    20         g_cs.Unlock(); 21     }    22     // 上面代码中，func1的效果和func2等价, 这两个函数都是一开始就对g_cs上锁,运行完后解锁之。 23 @endcode 24 */25 class CLock26 {27     ......28 }

函数说明

1 /** 2 @brief 当前线程修眠uMilliSec毫秒。 3 @warning 这是一个static函数，只能用来处理调用者的当前线程。 4 @param uMilliSec 让当前线程休眠的毫秒数。 5 */ 6 static inline VOID GoSleep(UINT32 uMilliSec);

类、结构体、联合体的成员变量说明

1 TYTE para_name; ///< 一些说明。

重点模块

单独一页出来说明 

 1 /**  2 @page TilerCache 地图瓦片缓存策略  3  4 设计需求: 5 -# 将从服务器获取的地图瓦片以文件的形式保存在本地，减少网络负担。  6 -# 为方便本地查找，对瓦片数据以索引+数据的形式进行管理；索引表用来查找瓦片，瓦片的数据保存到数据文件中。  7 -# ... 8  9 宏定义 10 @code 11 #define TILER_INDEX_READ_MAX  0x1000    // 一个block包含多少个瓦片 12 #define TILER_INDEX_BLOCK_MAX  6        // 最多缓存6*TILER_INDEX_READ_MAX个瓦片 13 #define TILER_DATA_BLOCK_MAX  2         // 多少个block数据保存为一个文件 14 #define TILER_DATA_FILE_MAX  (TILER_INDEX_BLOCK_MAX/TILER_DATA_BLOCK_MAX)  // 数据文件的个数 15 @endcode16 17 数据结构 18 -# 瓦片索引的数据结构 (略) 19 -# 索引文件头的数据结构 (略)20 21 实现流程图 22 @image html TilerCache_2.JPG 23 */ 

注意点

1、class的注释需要@brief 才能显示出来
2、如果哪个函数或类不需要生成文档，可以使用/// @cond /// @endcond，比如
/// @cond
public void fun(void);
/// @endcond