轉自:http://blog.csdn.net/augusdi/article/details/6749845
代碼寫多了難免需要做文檔,給自己還是給別人看都需要如此,這次XBOX360製作,前期沒怎麼寫註釋,回頭改Bug都要猜半天自己寫的代碼是什麼意思。更別提別人寫的東西,100行代碼也沒有一句註釋,幸好不是我維護,否則要瘋掉了。
花了一天功夫嘗試了一下Doxygen的使用,還好不難,但是有些磕磕絆絆,它自己的文檔也說不清楚,網上搜出來的教程也只是給出樣子,遇到的問題還是靠自己嘗試了幾十次才搞定。
不管如何,常用的東西都可以弄出來了。貼在下面:
-----------------------------------------------------------------------------------
1.所有註釋都可以使用///開始(C++風格)。
2.類體前必須加上///描述,否則會產生警告【Compound 類名 is not documented】
描述中最好不要帶有此類的類名,否則會產生兩個鏈接(但指向同一個文件)影響美觀。
3.public和protected會自動生成,但是private要在Expert的Build選項裏勾中EXTRACT_PRIVATE,static成員也是如此。
4.函數註釋方式
/// Constructor【函數描述】
/// @param [in] pos The position of Camera in world coordinate 【參數描述1】
/// @param [in] lookat The point Camera looks at in world coordinate 【參數描述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
兩種方式產生的結果不同。前者會單獨產生一塊Member Data Documentation註釋,後者會在Pubilc/Protected/Private Attributes變量描述後緊跟註釋。
6.@參數和\參數相同
7.產生描述順序和註釋順序相同,一般風格爲
/// 函數描述
/// @param 參數描述
/// @return 返回值描述
/// @retval 返回值1 返回值1描述
/// @retval 返回值2 返回值2描述
/// @remarks 注意事項
/// @note 注意事項,功能同@remarks,顯示字樣不同
/// @par 自定義圖塊,後面可跟示例代碼之類
/// @code(必須使用@endcode結束)
/// 示例代碼(無需縮進)
/// @endcode
/// @see 其他參考項【產生指向參考的鏈接】
函數代碼聲明
8.特殊符號
/// - 產生一個黑色圓點
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
};
兩種風格相同。
以下開始的項都是全局非類內定義,在文件最開始(我嘗試是在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. 非類內enum定義同10. 兩種風格相同。見9。
12. 非類內typedef定義同10. 風格說明見5。
-----------------------------------------------------------