流程
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 */ - @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
