doxygen注释语法（二）：函数、成员、枚举

目录(?)[+]

1. 函数注释
2. 成员注释
3. 枚举类型注释
4. 生成的CHM文件

6、函数注释

[]表示可选，{}表示重复0到N次，<>表示必须参数
函数注释语法是这样的

[cpp] view plain copy print ?

1. /** 
2. * @brief brief description 
3. * @author <list of authors> 
4. * {@param[in|out] <parameter‐name> <parameter description>} 
5. * @exception <exception‐object> <exception description> 
6. * {@exception <exception‐object> <exception description>} 
7. * @return <description of the return value> 
8. * {@return <description of the return value>} 
9. * @note 
10. * detailed description 
11. * @remarks <remark text> 
12. * {@remarks <remark text>} 
13. * [@deprecated <description>] 
14. * [@since when(time or version)] 
15. * [@see references{,references}] 
16. */  

/**
* @brief brief description
* @author <list of authors>
* {@param[in|out] <parameter‐name> <parameter description>}
* @exception <exception‐object> <exception description>
* {@exception <exception‐object> <exception description>}
* @return <description of the return value>
* {@return <description of the return value>}
* @note
* detailed description
* @remarks <remark text>
* {@remarks <remark text>}
* [@deprecated <description>]
* [@since when(time or version)]
* [@see references{,references}]
*/

@可用\代替，但我倾向于用@。
@param[in|out]     参数名及其解释
@exception            用来说明异常类及抛出条件
@return                   对函数返回值做解释
@note                      表示注解，暴露给源码阅读者的文档
@remark                表示评论，暴露给客户程序员的文档
@since                   表示从那个版本起开始有了这个函数
@deprecated        引起不推荐使用的警告
@see                      表示交叉参考
函数的详细注释用@note代替详细注释，因为详细注释要空行隔开，容易忘记。

示例：

[cpp] view plain copy print ?

1. /**  
2. * @brief 创建三级PagedLOD场景 
3. * @author Archie 
4. * @return 组节点 
5. * @note 
6. * 根据内容创建一个三级结构的分页LOD场景 
7. * @since 1.0.0.0 
8. */  
9. osg::ref_ptr<osg::Group> createPagedLOD()  
10. {  
11.     osg::ref_ptr<osg::PagedLOD> page= new osg::PagedLOD();  
12.     page->setCenter(osg::Vec3(0.0f, 0.0f ,0.0f));  
13.   
14.     // 添加节点，设置0级的内容为cow.osg Level0   
15.     page->setFileName(0,"cow.osg");  
16.     page->setRange(0, 0.0f, 50.0f);  
17.   
18.     page->setFileName(1,"glider.osg");//Level 1   
19.     page->setRange(1,50.0f, 100.0f);  
20.   
21.     page->setFileName(2,"cessna.osg");  
22.     page->setRange(2,100.0f, 200.0f);  
23.   
24.     return page.get();  
25. }  
26. /** 
27. * @brief 主函数 
28. * @author Archie 
29. * @param[in] argc 从命令行接受的参数个数 
30. * @param[in] argv 命令行接受的参数数组指针 
31. * @return 0如果正常，否则为非0值 
32. * @note 
33. * 本函数为程序的入口函数，三维场景图形过程在主函数中进行数据准备和显示 
34. * @since 1.0.0.0 
35. */  
36. int _tmain(int argc, _TCHAR* argv[])  
37. {  
38.     osg::ref_ptr<osgViewer::Viewer> viewer = new osgViewer::Viewer();  
39.     osg::ref_ptr<osg::Group> root= new osg::Group();  
40.   
41.     //矩阵变换节点  继承自Group   
42.     osg::ref_ptr<osg::MatrixTransform> mt= new osg::MatrixTransform();  
43.     mt->addChild(createPagedLOD());  
44.   
45.     osg::Matrix m;  
46.     m.makeRotate(60.0f, 0.0f,0.0f, 1.0f);// 旋转   
47.     mt->setMatrix(m);  
48.   
49.     root->addChild(mt.get());  
50.   
51.     osgDB::writeNodeFile(*root,"page.osg");  
52.   
53.     osgUtil::Optimizer optimizer;  
54.     optimizer.optimize(root.get());  
55.   
56.     viewer->setSceneData(root.get());  
57.     viewer->realize();  
58.     viewer->run();  
59.   
60.     return 0;  
61. }  

/** 
* @brief 创建三级PagedLOD场景
* @author Archie
* @return 组节点
* @note
* 根据内容创建一个三级结构的分页LOD场景
* @since 1.0.0.0
*/
osg::ref_ptr<osg::Group> createPagedLOD()
{
	osg::ref_ptr<osg::PagedLOD> page= new osg::PagedLOD();
	page->setCenter(osg::Vec3(0.0f, 0.0f ,0.0f));

	// 添加节点，设置0级的内容为cow.osg Level0
	page->setFileName(0,"cow.osg");
	page->setRange(0, 0.0f, 50.0f);

	page->setFileName(1,"glider.osg");//Level 1
	page->setRange(1,50.0f, 100.0f);

	page->setFileName(2,"cessna.osg");
	page->setRange(2,100.0f, 200.0f);

	return page.get();
}
/**
* @brief 主函数
* @author Archie
* @param[in] argc 从命令行接受的参数个数
* @param[in] argv 命令行接受的参数数组指针
* @return 0如果正常，否则为非0值
* @note
* 本函数为程序的入口函数，三维场景图形过程在主函数中进行数据准备和显示
* @since 1.0.0.0
*/
int _tmain(int argc, _TCHAR* argv[])
{
	osg::ref_ptr<osgViewer::Viewer> viewer = new osgViewer::Viewer();
	osg::ref_ptr<osg::Group> root= new osg::Group();

	//矩阵变换节点  继承自Group
	osg::ref_ptr<osg::MatrixTransform> mt= new osg::MatrixTransform();
	mt->addChild(createPagedLOD());

	osg::Matrix m;
	m.makeRotate(60.0f, 0.0f,0.0f, 1.0f);// 旋转
	mt->setMatrix(m);

	root->addChild(mt.get());

	osgDB::writeNodeFile(*root,"page.osg");

	osgUtil::Optimizer optimizer;
	optimizer.optimize(root.get());

	viewer->setSceneData(root.get());
	viewer->realize();
	viewer->run();

	return 0;
}

单击函数后面的链接进入详细说明

7、成员注释

/**< 或///<用来注释成员，放在成员后面，格式如下：
int var; /**< Detailed description after the member */
int var; ///< Brief description after the member
此语法对函数成员也适用。

示例：

[cpp] view plain copy print ?

1. int ro;/**<旋转角度*/  
2. double length;///<距离   
3. double area;///<面积  

int ro;/**<旋转角度*/
double length;///<距离
double area;///<面积

点击进入源文件PagedLOD.cpp，选择变量可以查看变量说明

8、枚举类型注释

[cpp] view plain copy print ?

1. /** @brief Another enum, with inline docs */  
2. enum AnotherEnum  
3. {  
4.     V1,/**< value 1 */  
5.     V2 /**< value 2 */  
6. };  

/** @brief Another enum, with inline docs */
enum AnotherEnum
{
    V1,/**< value 1 */
    V2 /**< value 2 */
};

枚举可看做类的一种特殊形式，添加简单说明，Doxygen会根据其后面的enum解析出枚举类型，下例中黑色和白色为成员变量注释。

示例：

[cpp] view plain copy print ?

1. /** @brief 枚举类型，内联文档 */  
2. enum Color  
3. {  
4. Black, /**< 黑色 */  
5. White /**< 白色 */  
6. };  

/** @brief 枚举类型，内联文档 */
enum Color
{
Black, /**< 黑色 */
White /**< 白色 */
};

--------------------------------------------------------------------------------------------

点击进入源文件，找到枚举类型

9、生成的CHM文件