1、JavaDoc注释风格
注释风格有多种,本文采用JavaDoc注释风格
Java风格如下,注释第一行为/**,然后中间每一行注释以*号开始,且为了方便阅读,一般*后空一字符,最后一行以*/结束,*与上一行*对齐。
- /**
- *
- *
- *
- */
/** * * * */
2、简要注释和详细注释
注释应写在对应的函数或变量前面。JavaDoc风格下,自动会把第一个句号
"." 前的文本作为简要注释,后面的为详细注释。你也可以用空行把简要注释和详细注释分开。注意要设置JAVADOC_AUTOBRIEF设为YES。@brief 表面后面为简要注释,当然,仅仅写下下面几行字,在说明文档中什么都不会出现,必须表明是对什么的注释,比如是对文件还是类还是成员的注释。
- /**
- * @brief 简要注释Brief Description.
- *
- * 这里是详细注释Detailed Description
- */
/** * @brief 简要注释Brief Description. * * 这里是详细注释Detailed Description */
3、注释从高级层次到细节层次
先从文件开始注释,然后是所在文件的全局函数、结构体、枚举变量、命名空间→命名空间中的类→成员函数和成员变量。
4、文件头注释@file
因为文件不在任何东西里面,所以不能像类、函数等在上方放注释,只能用@file方式定义,其格式如下
- /** @file
- * @brief brief description
- * @author <list of authors>
- * [@author <authors description>]
- * @date <date>
- * @version <version number>
- * @note
- * detailed description
- */
/** @file * @brief brief description * @author <list of authors> * [@author <authors description>] * @date <date> * @version <version number> * @note * detailed description */
[]表示可选,{}表示重复0到N次,<>表示必须参数
一般@file后我们空着,Doxygen会默认为是@file所在文件的文件名。
@brief为建明注释
@aothor为作者列表
@date为日期
@version为版本号
@note为注解
上面五项共同构成文件的详细描述,考虑如下注释
- /** @file
- * @brief 分页细节层次(LOD).
- * @author Archie
- * @date June 29,2013
- * @version 1.0.0.0
- * @note
- * 分页细节层次(LOD)是Level Of Details
- */
- #include "stdafx.h"
- #include <osgViewer/Viewer>
- #include <osg/Node>
- #include <osg/Geode>
- #include <osg/Group>
- #include <osg/PagedLOD>
- #include <osg/PositionAttitudeTransform>
- #include <osg/MatrixTransform>
- #include <osgDB/ReadFile>
- #include <osgDB/WriteFile>
- #include <osgGA/TrackballManipulator>
- #include <osgUtil/Optimizer>
- #include <iostream>
/** @file * @brief 分页细节层次(LOD). * @author Archie * @date June 29,2013 * @version 1.0.0.0 * @note * 分页细节层次(LOD)是Level Of Details */ #include "stdafx.h" #include <osgViewer/Viewer> #include <osg/Node> #include <osg/Geode> #include <osg/Group> #include <osg/PagedLOD> #include <osg/PositionAttitudeTransform> #include <osg/MatrixTransform> #include <osgDB/ReadFile> #include <osgDB/WriteFile> #include <osgGA/TrackballManipulator> #include <osgUtil/Optimizer> #include <iostream>
其中的详细描述如图所示
文档整体结构如下组织
- 首先是简要说明 ,点击旁边的“更多”可以查看详细描述
- 接着是包含的文件列表
- 然后是引用关系图
- 如果勾选了前面的源码选项还会附带源码
- 然后是全局函数等
- 最后是详细描述
其中使用graphviz生成的引用关系图如下,点击任意文件可查看此文件的源代码
5、类注释
类注释的格式
- /**
- * @class <class‐name> [header‐file] [<header‐name]
- * @brief brief description
- * @author <list of authors>
- * @note
- * detailed description
- */
/** * @class <class‐name> [header‐file] [<header‐name] * @brief brief description * @author <list of authors> * @note * detailed description */
header‐file是类声明所在的头文件名字,header‐name是要显示的链接文字,一般为头文件的真实路径在include<XX>中显示。
- /**
- * @class CTest PagedLOD.cpp CTest.h
- * @brief 测试
- * @author Archie
- * @note
- * 测试Doxygen的类注释
- */
- class CTest
- {
- public:
- private:
- }
/** * @class CTest PagedLOD.cpp CTest.h * @brief 测试 * @author Archie * @note * 测试Doxygen的类注释 */ class CTest { public: private: }
以上代码仍是在PagedLOD.cpp中定义,为了演示方便,CTest.h为假定的路径名(并未创建)。
点击CTest,进入类CTest介绍,其中CTest前的C表示索引字母为C,点击类索引可以根据索引字母查找类。
------------------
类索引根据类的首字母进行索引排序
1、JavaDoc注释风格
注释风格有多种,本文采用JavaDoc注释风格
Java风格如下,注释第一行为/**,然后中间每一行注释以*号开始,且为了方便阅读,一般*后空一字符,最后一行以*/结束,*与上一行*对齐。
- /**
- *
- *
- *
- */
/** * * * */
2、简要注释和详细注释
注释应写在对应的函数或变量前面。JavaDoc风格下,自动会把第一个句号
"." 前的文本作为简要注释,后面的为详细注释。你也可以用空行把简要注释和详细注释分开。注意要设置JAVADOC_AUTOBRIEF设为YES。@brief 表面后面为简要注释,当然,仅仅写下下面几行字,在说明文档中什么都不会出现,必须表明是对什么的注释,比如是对文件还是类还是成员的注释。
- /**
- * @brief 简要注释Brief Description.
- *
- * 这里是详细注释Detailed Description
- */
/** * @brief 简要注释Brief Description. * * 这里是详细注释Detailed Description */
3、注释从高级层次到细节层次
先从文件开始注释,然后是所在文件的全局函数、结构体、枚举变量、命名空间→命名空间中的类→成员函数和成员变量。
4、文件头注释@file
因为文件不在任何东西里面,所以不能像类、函数等在上方放注释,只能用@file方式定义,其格式如下
- /** @file
- * @brief brief description
- * @author <list of authors>
- * [@author <authors description>]
- * @date <date>
- * @version <version number>
- * @note
- * detailed description
- */
/** @file * @brief brief description * @author <list of authors> * [@author <authors description>] * @date <date> * @version <version number> * @note * detailed description */
[]表示可选,{}表示重复0到N次,<>表示必须参数
一般@file后我们空着,Doxygen会默认为是@file所在文件的文件名。
@brief为建明注释
@aothor为作者列表
@date为日期
@version为版本号
@note为注解
上面五项共同构成文件的详细描述,考虑如下注释
- /** @file
- * @brief 分页细节层次(LOD).
- * @author Archie
- * @date June 29,2013
- * @version 1.0.0.0
- * @note
- * 分页细节层次(LOD)是Level Of Details
- */
- #include "stdafx.h"
- #include <osgViewer/Viewer>
- #include <osg/Node>
- #include <osg/Geode>
- #include <osg/Group>
- #include <osg/PagedLOD>
- #include <osg/PositionAttitudeTransform>
- #include <osg/MatrixTransform>
- #include <osgDB/ReadFile>
- #include <osgDB/WriteFile>
- #include <osgGA/TrackballManipulator>
- #include <osgUtil/Optimizer>
- #include <iostream>
/** @file * @brief 分页细节层次(LOD). * @author Archie * @date June 29,2013 * @version 1.0.0.0 * @note * 分页细节层次(LOD)是Level Of Details */ #include "stdafx.h" #include <osgViewer/Viewer> #include <osg/Node> #include <osg/Geode> #include <osg/Group> #include <osg/PagedLOD> #include <osg/PositionAttitudeTransform> #include <osg/MatrixTransform> #include <osgDB/ReadFile> #include <osgDB/WriteFile> #include <osgGA/TrackballManipulator> #include <osgUtil/Optimizer> #include <iostream>
其中的详细描述如图所示
文档整体结构如下组织
- 首先是简要说明 ,点击旁边的“更多”可以查看详细描述
- 接着是包含的文件列表
- 然后是引用关系图
- 如果勾选了前面的源码选项还会附带源码
- 然后是全局函数等
- 最后是详细描述
其中使用graphviz生成的引用关系图如下,点击任意文件可查看此文件的源代码
5、类注释
类注释的格式
- /**
- * @class <class‐name> [header‐file] [<header‐name]
- * @brief brief description
- * @author <list of authors>
- * @note
- * detailed description
- */
/** * @class <class‐name> [header‐file] [<header‐name] * @brief brief description * @author <list of authors> * @note * detailed description */
header‐file是类声明所在的头文件名字,header‐name是要显示的链接文字,一般为头文件的真实路径在include<XX>中显示。
- /**
- * @class CTest PagedLOD.cpp CTest.h
- * @brief 测试
- * @author Archie
- * @note
- * 测试Doxygen的类注释
- */
- class CTest
- {
- public:
- private:
- }
/** * @class CTest PagedLOD.cpp CTest.h * @brief 测试 * @author Archie * @note * 测试Doxygen的类注释 */ class CTest { public: private: }
以上代码仍是在PagedLOD.cpp中定义,为了演示方便,CTest.h为假定的路径名(并未创建)。
点击CTest,进入类CTest介绍,其中CTest前的C表示索引字母为C,点击类索引可以根据索引字母查找类。
------------------
类索引根据类的首字母进行索引排序