版本比较
标识
- 该行被添加。
- 该行被删除。
- 格式已经改变。
概述
Doxygen是一个从程序源码生成文档的工具,主要用于C/C++源码,也支持其他如PHP, Java, Python等代码。具体来说,Doxygen服务于以下两个目的:
- 从带注释标记的源码中生成文档,一般是HTML格式,当然也支持其他可离线查看的格式。生成的文档是直接从源码的注释中提取的,这样程序员就可以边写代码边写注释,同时完成编码和文档工作。
- 从源码中提取代码结构,生成整个工程的框架文档,并且提供可视化的展示,比如UML类图,继承图,头文件包含等。
除了从源码中生成文档外,Doxygen也支持直接创建正常的文档,这点Doxygen和Gitbook类似,Doxygen的在线文档就是用Doxygen编写的。
参考链接:
https://www.doxygen.nl/index.html
https://www.cnblogs.com/silencehuan/p/11169084.html
安装
参考https://www.doxygen.nl/manual/install.html,在Ubuntu系统下,直接 apt install doxygen
即可,安装完成之后,Doxygen的执行程序为doxygen
。
代码块 |
---|
# doxygen --version
1.8.13 |
使用
...
, doxygen
的使用包括3个步骤:
- 生成模板配置文件
- 调整模板配置文件中的选项
- 根据配置生成文档
使用 doxygen -g <config-file>
命令生成模板配置文件,<config-file>为指定的配置文件名,如果不提供文件名,默认使用Doxyfile
作为配置文件名。如果当前目录已经存在同名的文件,那doxygen会将当前目录的文件重命名成<config-file>.bak,再创建配置文件。
生成的配置文件包含了一系列的键值对,格式为TAGNAME = VALUE
的形式, #
开头的为注释,其中比较重要的注释项有以下几项:
代码块 |
---|
# 指定编码为utf-8
DOXYFILE_ENCODING = UTF-8
# 项目名
PROJECT_NAME = "sylar"
# 项目描述
PROJECT_BRIEF = "C++高性能服务器框架"
# 语言(中文)
OUTPUT_LANGUAGE = Chinese
# 不生成LATEX文档
GENERATE_LATEX = NO |
下一步是生成文档,使用 doxygen <config-file>
命令即可,生成的HTML文档位于当前目录的html文件夹,入口是index.html。
注释规范
使用Doxygen重点就是根据Doxygen指定的格式来写注释,只有符合Doxygen格式要求的注释才会体现在生成的文档中,这里参考官方文档,把一些常用的注释格式过一遍。另外,如果你使用的是VS Code编辑器,那么可以通过安装Doxygen Documentation Generator这个插件来自动补全Doxygen注释,非常方便。
Doxygen的文档注释一般位于要注释对象的前面,如果是文件的注释,则一般在文件开头。注释以注释块或单行注释的形式体现,其中注释块一般使用下面的格式:
代码块 |
---|
/**
* ...
*/ |
单行注释一般格式为:
代码块 |
---|
/// ... |
以上两种格式的注释可被Doxygen识别并生成到文档中,除此外,Doxygen还支持其他格式的注释块,这点参考官方文档 Special comment blocks。
在注释块里可以加入命令,以实现更详细的标注,比如提示函数功能,参数,返回值等,以下是一个示例:
代码块 |
---|
/**
* @brief 获取当前栈信息的字符串
* @param[in] size 栈的最大层数
* @param[in] skip 跳过栈顶的层数
* @param[in] prefix 栈信息前输出的内容
* @return 栈回溯字符串描述
*/
std::string BacktraceToString(int size = 64, int skip = 2, const std::string& prefix = ""); |
该注释块会生成以下的文档信息:
Image Added
Doxygen支持众多注释命令,所有的命令都以\或@开头,下面是一些常用的命令,另外,这里有一份完整的命令列表。
命令 | 功能 |
---|---|
\author { list of authors } | 描述作者 |
\version { version number } | 描述版本 |
\date { date description } | 描述日期 |
\brief { brief description } | 概要注释 |
\details { detailed description } | 详细注释,位于概要注释下面,另起一行 |
\param['dir'] <parameter-name> { parameter description } | 参数说明,可附带参数方向("[in]", "[out]" "[in,out]") |
\return { description of the return value } | 描述返回含义 |
\retval <return value> { description } | 描述返回值的含义,可以有多个\retval |
\note | 描述注意事项 |
\pre | 描述前置条件 |
\post | 描述后置条件 |
\deprecated | 描述已作废函数 |
\code \endcode | 在注释中写一段代码 |
\bug | 描述一个bug |
\warning | 描述一个警告 |
\copyright | 声明版权 |
Doxygen注释实例
项目注释
代码块 |
---|
/**@mainpage sylar C++高性能服务器框架
*******************************************************************************
* <table>
* <tr><th>Project <td>sylar
* <tr><th>Author <td>sylar
* <tr><th>Source <td>https://github.com/sylar-yin/sylar
* </table>
* @section 项目描述
* C++高性能分布式服务器框架,webserver,websocket server,自定义tcp_server(包含日志模块,配置模块,线程模块,协程模块,协程调度模块,io协程调度模块,hook模块,socket模块,bytearray序列化,http模块,TcpServer模块,Websocket模块,Https模块等, Smtp邮件模块, MySQL, SQLite3, ORM,Redis,Zookeeper)
*
* @section 日志模块
*支持流式日志风格写日志和格式化风格写日志,支持日志格式自定义,日志级别,多日志分离等等功能 流式日志使用:SYLAR_LOG_INFO(g_logger) << "this is a log"; 格式化日志使用:SYLAR_LOG_FMT_INFO(g_logger, "%s", "this is a log"); 支持时间,线程id,线程名称,日志级别,日志名称,文件名,行号等内容的自由配置
*
* @section 配置模块
*采用约定由于配置的思想。定义即可使用。不需要单独去解析。支持变更通知功能。使用YAML文件做为配置内容。支持级别格式的数据类型,支持STL容器(vector,list,set,map等等),支持自定义类型的支持(需要实现序列化和反序列化方法)使用方式如下:
@code
static sylar::ConfigVar<int>::ptr g_tcp_connect_timeout =
sylar::Config::Lookup("tcp.connect.timeout", 5000, "tcp connect timeout");
@endcode
*定义了一个tcp连接超时参数,可以直接使用 g_tcp_connect_timeout->getValue() 获取参数的值,当配置修改重新加载,该值自动更新 上述配置格式如下:
@code
tcp:
connect:
timeout: 10000
@endcode
*
**********************************************************************************
*/ |
渲染效果:
Image Added
文件注释
代码块 |
---|
/**
* @file scheduler.c
* @author sylar.yin 564628276@qq.com
* @brief 协程调度器封装
* @version 1.0
* @date 2019-05-28
* @copyright Copyright (c) 2019年 sylar.yin All rights reserved (www.sylar.top)
* @attention
* IO协程调度未实现 \n
* 调度器idle实为忙等待,待修复
* @par 修改日志:
* <table>
* <tr><th>Date <th>Version <th>Author <th>Description
* <tr><td>2021/06/05 <td>1.0 <td>sylar <td>创建初始版本
* </table>
*
*/ |
渲染效果
Image Added
类注释
代码块 |
---|
/*!
* \brief Pretty nice class.
* \details This class is used to demonstrate a number of section commands.
* \author John Doe
* \author Jan Doe
* \version 4.1a
* \date 1990-2011
* \pre First initialize the system.
* \bug Not all memory is freed when deleting an object of this class.
* \warning Improper use can crash your application
* \copyright GNU Public License.
*/
class SomeNiceClass {}; |
渲染效果:
Image Added
目录 |
---|