java doxygen_Doxygen 使用总结
转自:http://ticktick.blog.51cto.com/823160/188674
5 Doxygen的注释风格
5.1 综述
在每个代码项中都可以有两类描述, 这两类描述将在文档中格式化在一起: 一种就是brief描述, 另一种就是detailed。 两种都是可选的,但不能同时没有。
顾名思义, 简述(brief)就是在一行内简述地描述。而详细描述(detailed description)则提供更长, 更详细的文档。
Doxygen支持c风格注释、c++风格注释以及javaDoc风格注释等,下面将分别予以介绍。
若需要通过Doxygen生成漂亮的文档,一般有如下几个地方需要使用Doxygen支持的风格进行注释:
1) 文件头(包括.h和.cpp)
主要用于声明版权,描述本文件实现的功能,以及文件版本信息等
2) 类的定义
主要用于描述该类的功能,同时也可以包含使用方法或者注意事项的简要描述
3) 类的成员变量定义
在类的成员变量上方,对该成员变量进行简要地描述
4) 类的成员函数定义
在类定义的成员函数上方,对该成员函数功能进行简要描述
5) 函数的实现在函数的实现代码处,详细描述函数的功能、参数的含义、返回值的含义、使用本函数需要注意的问题、本函数使用其他类或函数的说明等
5.2 Doxygen支持的指令
5.2.1 概述
可以在注释中加一些Doxygen支持的指令,主要作用是控制输出文档的排版格式,使用这些指令时需要在前面加上“\”或者“@”(JavaDoc风格)符号,告诉Doxygen这些是一些特殊的指令,通过加入这些指令以及配备相应的文字,可以生成更加丰富的文档,下面对比较常用的指令做一下简单介绍。
5.2.2 常用指令介绍
@file
档案的批注说明。
@author
作者的信息
@brief
用于class 或function的简易说明
eg:
@brief本函数负责打印错误信息串
@param
主要用于函数说明中,后面接参数的名字,然后再接关于该参数的说明
@return
描述该函数的返回值情况
eg:
@return 本函数返回执行结果,若成功则返回TRUE,否则返回FLASE
@retval
描述返回值类型
eg:
@retval NULL空字符串。
@retval !NULL非空字符串。
@note
注解
@attention
注意
@warning
警告信息
@enum
引用了某个枚举,Doxygen会在该枚举处产生一个链接
eg:
@enum CTest::MyEnum
@var
引用了某个变量,Doxygen会在该枚举处产生一个链接
eg:
@var CTest::m_FileKey
@class
引用某个类,
格式:@class [] []
eg:
@class CTest "inc/class.h"
@exception
可能产生的异常描述
eg:
@exception 本函数执行可能会产生超出范围的异常
5.3 JavaDoc风格的注释
5.3.1 概述
JavaDoc风格的注释风格主要使用下面这种样式:即在注释块开始使用两个星号‘*‘
/** description
* description
* description
*/
5.3.2 简述与详述的方式
Doxygen支持的块(类、函数、结构体等)的注释描述分为两种:简述 和 详述
一般注释的描述由简述开始,经过特殊分隔方式后,后面紧跟详述的内容,javaDoc风格可以使用的分隔方法有以下两种:
1) 使用 \brief 参数标识,空行作为简述和详述的间隔标识
/*! @brief Brief description.
* description continued.
*
* Detailed description starts here.
*/
2) 直接使用javaDoc风格,javaDoc风格自动以简述开头,以空行(或者小数点加空格)作为简述与详述的分割
/** Brief description
* description continued
*
* Detailed description starts here.
*/
/** Brief description
* description continued . (注意:这里有一个小数点,加上一个空格)
* Detailed description starts here.
*/
5.3.3 文件头注释示例
5.3.4 类定义注释示例
/** 本类的功能:打印错误信息
*
* 本类是一个单件
* 在程序中需要进行错误信息打印的地方
*/
class CPrintError
{
……
}
5.3.5 类成员变量定义示例
(1)在成员变量上面加注释的格式
/** 成员变量描述 */
int m_Var;
(2)在成员变量后面加注释的格式int m_color; /**
5.3.6 成员函数的注释示例
/** 下面是一个含有两个参数的函数的注释说明(简述)
*
* 这里写该函数的详述信息
* @param a 被测试的变量(param描述参数)
* @param s 指向描述测试信息的字符串
* @return 测试结果 (return描述返回值)
* @see Test() (本函数参考其它的相关的函数,这里作一个链接)
* @note (note描述需要注意的问题)
*/
int testMe(int a,const char *s);
5.3.7 枚举变量的注释示例
/** 颜色的枚举定义
*
* 该枚举定义了系统中需要用到的颜色\n
* 可以使用该枚举作为系统中颜色的标识
*/
enum TEnum
{
RED, /**
BLUE, /**
YELLOW /**
}enumVar;
5.4 C++风格的注释
5.4.1 概述
C++的注释风格主要使用下面这种样式:即在注释块开始使用三个反斜杠‘/’
其他地方其实与JavaDoc的风格类似,只是C++风格不用 “*” 罢了。
5.4.2 简述与详述
C++风格的简述与详述方式与javaDoc类似。
一般注释的描述由简述开始,经过特殊分隔方式后,后面紧跟详述的内容,C++风格可以使用的分隔方法有以下两种:
(1)使用 \brief 参数标识,空行作为简述和详述的间隔标识
/// \brief Brief description.
/// description continued.
///
/// Detailed description starts here.
///
(2) 使用以空行(或者小数点加空格)作为简述与详述的分割
/// Brief description
/// description continued.
///
/// Detailed description starts here.
以小数点加空格作为分隔如下:
/// Brief description
/// description continued . (注意:这里有一个小数点,加上一个空格)
/// Detailed description starts here.
///
5.4.3 注释风格约定
1. 一个代码块(类、函数、结构等)的概述采用单行的”///”加一个空格开头的注释,并写在该代码块声明的前面;
2. 一个代码块的详述采用至少两行的”///”加一个空格开头的注释,若不足两行第二行的开头也要写出来,并且放在代码块定义的前面;如果某代码没有声明只有定义或者相反,则在定义或者声明前面写上单行的概述+一个空行+多行的详述;
3. 枚举值列表的各项、结构域的各项等采用在本行最后添加”///
4. 对变量的定义采用在变量上面加单行”///”加一个空格开头的注释(相当于是给改变量一个概述);
5. 函数的参数用”/// @param”+一个空格开头的行描述在函数的详述里面;
6. 函数的返回值用”/// @return”+一个空格开头的行描述在函数的详述里面;
7. 函数之间的参考用”/// @see”+一个空格开头的行描述在函数的详述里面;
8. 文件头的版权以及文件描述的注释参见例代码。
5.4.4 文件头注释示例
5.4.5 类定义注释示例
/// 本类的功能:打印错误信息
///
/// 本类是一个单件
/// 在程序中需要进行错误信息打印的地方
class CPrintError
{
……
}
5.4.6 类成员变量定义示例
(1)在成员变量上面加注释的格式
/// 成员变量描述
int m_Var;
(2)在成员变量后面加注释的格式int m_color; /// 颜色变量
5.4.7 成员函数的注释示例
/// 下面是一个含有两个参数的函数的注释说明(简述)
///
/// 这里写该函数的详述信息
/// @param a 被测试的变量(param描述参数)
/// @param s 指向描述测试信息的字符串
/// @return 测试结果 (return描述返回值)
/// @see Test() (本函数参考其它的相关的函数,这里作一个链接)
/// @note (note描述需要注意的问题)
int testMe(int a,const char *s);
5.4.8 枚举变量的注释示例
/// 颜色的枚举定义
///
/// 该枚举定义了系统中需要用到的颜色\n
/// 可以使用该枚举作为系统中颜色的标识
enum TEnum
{
RED, ///
BLUE, ///
YELLOW ///
}enumVar;
5.5 需要注意的问题
(1)Doxygen会忽略你在注释中加入的多余的换行,如果你希望保留两行注释之间的空行,那么,在该行加入\n
6 Doxygen使用的常见问题小结
6.1 中文问题:中文注释在文档中是乱码
解决:在expert中的INPUT选项页的INPUT_ENCODEING中填入“GB2312”,这样基于GB的文本编辑器生成的代码就可以正常使用了。
6.2 图形问题:无法绘制类图协作图等图形。
解决:首先确保安装了graphviz for win,注意不是wingraphviz,后者是一个graphviz的com封装,但是doxygen并不是基于它开发的,所以装了也没用。然后在expert的DOT_PATH中填入graphviz的安装路径。接着在wizard的diagram中选择需要生成的图形类别就可以了。
如果出现无法包含.map文件的错误,可以将工作目录设置成html,并将html中所有文件都清除再试。这个问题的原因还不太确定。
6.3 输出chm的问题:如何输出.chm文件
配置时注意expert中的HTML页:选中“GENERATE_HTMLHELP”,然后在CHM_FILE中填上想要的chm文件名。
HHC_LOCATION中输入hhc.exe文件的路径。hhc.exe可以通过安装HTML Help Workshop获得。
或者使用HTML Help Workshop来编译Doxygen生成的html文件夹中的.hhp文件,编译完成后即可在该html文件夹中找到对应的chm文件
6.4 Doxygen无法为DLL中定义的类 导出文档
例如:
class __declspec(dllexport) CClassName:public CObject
{
}
目前发现Doxygen无法识别出DLL中定义的类。
java doxygen_Doxygen 使用总结相关推荐
- springboot实现SSE服务端主动向客户端推送数据,java服务端向客户端推送数据,kotlin模拟客户端向服务端推送数据
SSE服务端推送 服务器向浏览器推送信息,除了 WebSocket,还有一种方法:Server-Sent Events(以下简称 SSE).本文介绍它的用法. 在很多业务场景中,会涉及到服务端向客户端 ...
- Java 获取当前时间之后的第一个周几,java获取当前日期的下一个周几
Java 获取当前时间之后的第一个周几,java获取当前日期的下一个周几 //获得入参的日期 Calendar cd = Calendar.getInstance(); cd.setTime(date ...
- 在k8s中使用gradle构建java web项目镜像Dockerfile
在k8s中使用gradle构建java web项目镜像Dockerfile FROM gradle:6-jdk8 AS build COPY --chown=gradle:gradle . /home ...
- Java | kotlin 手动注入bean,解决lateinit property loginService has not been initialized异常
kotlin.UninitializedPropertyAccessException: lateinit property loginService has not been initialized ...
- SpringBoot项目使用nacos,kotlin使用nacos,java项目使用nacos,gradle项目使用nacos,maven项目使用nacos
SpringBoot项目使用nacos kotlin demo见Gitte 一.引入依赖 提示:这里推荐使用2.2.3版本,springboot与nacos的依赖需要版本相同,否则会报错. maven ...
- OpenAPI使用(swagger3),Kotlin使用swagger3,Java使用swagger3,gradle、Maven使用swagger3
OpenAPI使用(swagger3) demo见Gitte 一.背景及名词解释 OpenAPI是规范的正式名称.规范的开发工作于2015年启动,当时SmartBear(负责Swagger工具开发的公 ...
- Gradle错误提示:Java home supplied via ‘xxx.xxx.xxx‘ is invalid
Gradle错误提示:Java home supplied via 'org.gradle.java.home' is invalid 描述:在使用idea采用gradle进行依赖的管理功能,当想切换 ...
- 查看Hotspot源码,查看java各个版本源码的网站,如何查看jdk源码
java开发必知必会之看源码,而看源码的第一步则是找到源码
- java基本类型转换,随记
java基本类型转换: double double 转 long double random = Math.round(Math.random()*10000); long l = new Doubl ...
最新文章
- 【译】使用Kotlin和RxJava测试MVP架构的完整示例 - 第1部分
- mysql数据库备份总结_mysql中mysqlhotcopy备份数据库总结
- C/C++结构体字节对齐详解
- 在Tomcat上挂载预下载文件的方法
- 成功解决TypeError: Encoders require their input to be uniformly strings or numbers. Got [‘float‘, ‘int‘,
- Toast的另类应用及另类“拦截”Home键
- HTML中a标签/超链接标签的下划线怎么去掉
- [Java] webservice soap,wsdl 例子
- RabbitMQ学习——整合Spring AMQP、SpringBoot以及Spring Cloud Stream
- 简单算法系列之完数的计算
- 计算机专业中专自我鉴定范文,计算机专业中专生自我鉴定范文
- 使用cgroup限制某个程序对内存的使用
- 12306bycloud,免费开源抢票软件,无需安装,全平台可用
- 腾讯云短信(个人记录)
- svn status详解
- 用计算机弹c哩c哩数字,C哩C哩 - 在线打字测试(dazi.kukuw.com)
- CS224W-07:图神经网络二
- js将数组中相同项放在一个数组
- 用网线连接两台电脑传输文件
- 分子模拟榨干GPU性能的参数建议