【转】DOXYGEN简明实用教程

2019-07-19 13:49发布

代码写多了难免需要做文档，给自己还是给别人看都需要如此，这次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.特殊符号
/// -       产生一个黑 {MOD}圆点

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。

友情提示: 此问题已得到解决，问题已经关闭,关闭后问题禁止继续编辑，回答。