youwire

youwire

Doxygen編寫流程

youwire (2010-12-21 21:03:04) 評論 (1)

流程

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