Posted on 2009-03-04 21:31
活著就是幸福 閱讀(507)
評論(0) 編輯 收藏 所屬分類:
Project Management
代碼寫多了難免需要做文檔，給自己還是給別人看都需要如此，這次XBOX360制作，前期沒怎么寫注釋，回頭改Bug都要猜半天自己寫的代碼是什么意思。更別提別人寫的東西，100行代碼也沒有一句注釋，幸好不是我維護，否則要瘋掉了。
花了一天功夫嘗試了一下Doxygen的使用，還好不難，但是有些磕磕絆絆，它自己的文檔也說不清楚，網(wǎng)上搜出來的教程也只是給出樣子，遇到的問題還是靠自己嘗試了幾十次才搞定。
不管如何，常用的東西都可以弄出來了。貼在下面：
-----------------------------------------------------------------------------------
1.所有注釋都可以使用///開始(C++風格)。
2.類體前必須加上///描述，否則會產(chǎn)生警告【Compound 類名 is not documented】
描述中最好不要帶有此類的類名，否則會產(chǎn)生兩個鏈接(但指向同一個文件)影響美觀。
3.public和protected會自動生成，但是private要在Expert的Build選項里勾中EXTRACT_PRIVATE，static成員也是如此。
4.函數(shù)注釋方式
/// Constructor【函數(shù)描述】
/// @param [in] pos The position of Camera in world coordinate 【參數(shù)描述1】
/// @param [in] lookat The point Camera looks at in world coordinate 【參數(shù)描述2】
BaseCamera( const D3DXVECTOR3& pos, const D3DXVECTOR3& lookat );
5.變量注釋方式
D3DXVECTOR3 m_Position; /*!< Camera position point in world coordinate */ 或
D3DXVECTOR3 m_Position; ///< Camera position point in world coordinate
兩種方式產(chǎn)生的結(jié)果不同。前者會單獨產(chǎn)生一塊Member Data Documentation注釋，后者會在Pubilc/Protected/Private Attributes變量描述后緊跟注釋。
6.@參數(shù)和\參數(shù)相同
7.產(chǎn)生描述順序和注釋順序相同，一般風格為
/// 函數(shù)描述
/// @param 參數(shù)描述
/// @return 返回值描述
/// @retval 返回值1 返回值1描述
/// @retval 返回值2 返回值2描述
/// @remarks 注意事項
/// @note 注意事項，功能同@remarks,顯示字樣不同
/// @par 自定義圖塊，后面可跟示例代碼之類
/// @code(必須使用@endcode結(jié)束)
/// 示例代碼(無需縮進)
/// @endcode
/// @see 其他參考項【產(chǎn)生指向參考的鏈接】
函數(shù)代碼聲明
8.特殊符號
/// - 產(chǎn)生一個黑色圓點
9.定義在類體里面的enum
/// Camera types
enum CAMERA_TYPE
{
CAMERA_FIRST_VIEW,/*!< Camera that looks from the first view */
CAMERA_MODEL_VIEW,///< Camera that looks from the third view
};
兩種風格相同。
以下開始的項都是全局非類內(nèi)定義，在文件最開始(我嘗試是在include之前) 必須加上【/// \file 文件名】，否則不會生成注釋【沒有File Member頁】。
10. 定義在文件里面的宏
#define CAMERA_TYPE_NUMBER ///< The number of camera types. 或
#define CAMERA_TYPE_NUMBER /*!< The number of camera types. */
風格說明見5。
11. 非類內(nèi)enum定義同10. 兩種風格相同。見9。
12. 非類內(nèi)typedef定義同10. 風格說明見5。