doxygen注释语法（一）：JavaDoc注释风格、文件头和类注释

1、JavaDoc注释风格

注释风格有多种，本文采用JavaDoc注释风格

Java风格如下，注释第一行为/**,然后中间每一行注释以*号开始，且为了方便阅读，一般*后空一字符,最后一行以*/结束，*与上一行*对齐。

/**
 *
 *
 *
 */

2、简要注释和详细注释

注释应写在对应的函数或变量前面。JavaDoc风格下，自动会把第一个句号 "." 前的文本作为简要注释，后面的为详细注释。你也可以用空行把简要注释和详细注释分开。注意要设置JAVADOC_AUTOBRIEF设为YES。@brief 表面后面为简要注释，当然，仅仅写下下面几行字，在说明文档中什么都不会出现，必须表明是对什么的注释，比如是对文件还是类还是成员的注释。

/**
* @brief 简要注释Brief Description.
*
* 这里是详细注释Detailed Description
*/

3、注释从高级层次到细节层次

先从文件开始注释，然后是所在文件的全局函数、结构体、枚举变量、命名空间→命名空间中的类→成员函数和成员变量。

4、文件头注释@file

因为文件不在任何东西里面，所以不能像类、函数等在上方放注释，只能用@file方式定义，其格式如下

/** @file [file‐name]
* @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>

其中的详细描述如图所示

文档整体结构如下组织

1. 首先是简要说明 ，点击旁边的“更多”可以查看详细描述
2. 接着是包含的文件列表
3. 然后是引用关系图
4. 如果勾选了前面的源码选项还会附带源码
5. 然后是全局函数等
6. 最后是详细描述

 

 

其中使用graphviz生成的引用关系图如下，点击任意文件可查看此文件的源代码

5、类注释

类注释的格式

/**
* @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:
}

以上代码仍是在PagedLOD.cpp中定义，为了演示方便，CTest.h为假定的路径名（并未创建）。

点击CTest，进入类CTest介绍，其中CTest前的C表示索引字母为C，点击类索引可以根据索引字母查找类。

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

类索引根据类的首字母进行索引排序