代码写多了难免需要做文档,给自己还是给别人看都需要如此,这次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。
-----------------------------------------------------------
d
/// Copyright (C), 2005-2007.
/// \file WindowsNT
/// \brief Windows Nice Try.
/// \author Bill Gates
/// \author Several species of small furry animals gathered together
/// in a cave and grooving with a pict.
/// \version 4.0
/// \date 1996-1998
/// \warning This class may explode in your face.
/// \warning If you inherit anything from this class, you're doomed.
/// \ClassList:主要函数列表,每条记录应包括函数名及功能简要说明
/// 1. ....
/// \History: 修改历史记录列表,每条修改记录应包括修改日期、修改者及修改内容简述
/// Copyright (C), 2005-2007,
/// \file WindowsNT
/// \brief Windows Nice Try.
/// \author Bill Gates
/// \author Several species of small furry animals gathered together
/// in a cave and grooving with a pict.
/// \version 4.0
/// \date 1996-1998
/// \warning This class may explode in your face.
/// \warning If you inherit anything from this class, you're doomed.
/// \Function List:主要函数列表,每条记录应包括函数名及功能简要说明
/// 1. ....
/// \History: 修改历史记录列表,每条修改记录应包括修改日期、修改者及修改内容简述
/// \fn 函数名称
/// \brief 函数功能、性能等的描述.
/// \param[in] 参数 c a char.
/// \param[out] 参数 n an int.
/// \exception 异常 std::out_of_range parameter is out of range.
/// \return 返回值 a char pointer.
/// \class 类名字 类所在文件 "文件路径"
/// \brief 大纲描述.
///
/// 详细描述类的功能
/// A function.
/// A more elaborate description of the constructor.
///< a public variable. Details
标准类型的注释规范:
Enum
第一种方法
//
/// \enum TEnum
/// A description of the enum type.
//
enum TEnum {
Val1, /// \var Enum Val1
Val2 /// Enum Val2
};
第二种方法
enum在类内部定义
//
/// \enum An enum
/// More detailed enum description..
//
enum TEnum {
TVal1, ///< enum value TVal1.
TVal2, ///< enum value TVal2.
TVal3 ///< enum value TVal3.
}
*enumPtr, ///< enum pointer. Details.
enumVar; ///< enum variable. Details.
#define
macro宏定义
//
/// \def MAX(x,y)
/// Computes the maximum of \a x and \a y.
//
//
/// \typedef std::string YString
/// typedef YString.
//
/// \var int g_nCount
/// The description of the int value.
///
您可依照此规定在你自己的程序代码中加上对应的注释。其实,无论你有没有使用Doxygen ,
都不妨按照他的格式將注释写入,一方面是依照他的格式,並不会甘于您程序的运行。
另一方面,Doxygen 所定义的都是基本程序注释应当要的东西。
如果您使用Doxygen Wizard,可直接使用上面的Run 的按鈕或选项來制作说明文件。
如果是生产HTML文件,在HTML_OUTPUT 所指定的目录中的index.html將是您说明文件的首页。