Doxygen文档生成工具
Doxygen代码文档生成工具
文章目录
- Doxygen代码文档生成工具
-
- Doxygen
-
- Doxygen的注释
- vscode插件
- Doxygen实际使用
Doxygen
根据百度百科说法，Doxygen是一种开源的，跨平台的文档系统，支持C、C++、Java、Objective-C语言，可以生成在线的HTML参考手册或者离线的Latex、RTF参考手册
Doxygen是一种程序的文件产生工具，可以将程序中特定的注释转换成为说明文件。
-
可以对未归档的源文件，可以通过配置
Doxygen来提取代码结构 -
可以生成依赖图
-
可以生成继承图，协作图等
Doxygen的注释
代码的注释规则如下
模块对外的接口，仅在.h中提供注释信息
模块内部的辅助函数，或者私有的函数，仅在.c中保留注释信息
函数的注释一般有
- 函数功能
- 入口参数
- 返回值
- 注意事项
- 上下文
Doxygen是如何区分普通注释与输出注释的
对于C,C++注释一般有两种
//
/**/
Doxygen通过在里面加入*,/,!作为特殊标记
/*
* 正常注释
*/
Doxygen在注释第一个*后，设置*或!作为标志，如果检测到有这些，
就将接下来的注释作为导出文档来解释
同时，中间的*号可以省略，像这样
/**
要输出成文档的注释
*/
或者
/*!
要输出成文档的注释
*/
Doxygen如何从特殊注释中提取信息
Doxygen采用\和@作为特殊标记符，当在特殊注释里面检测到了特殊标记符，则接下来检测紧跟单词是不是Doxygen事先规定好的，如果是，则将按照特定的规则来解释紧跟着的注释；如果不是呢，则将\和@解释为普通文本，
是否是事先规定可以查看Doxygen官网文档
vscode插件
Doxygen Documentation Generator
在vscode中可以利用插件快速生成doxygen注释
vscode中用户seting.json插件设置如下
{
"window.zoomLevel": 0,
"editor.minimap.enabled": false,
"python.pythonPath": "C:\\Users\\jordan\\AppData\\Local\\Programs\\Python\\Python37\\python.exe",
"workbench.iconTheme": "vscode-icons",
"explorer.autoReveal": false, //取消左侧自动聚焦
"terminal.integrated.shell.windows": "D:\\Program Files\\Git\\bin\\bash.exe",
"terminal.external.windowsExec": "D:\\Program Files\\Git\\bin\\bash.exe",
"todo-tree.highlights.enabled": true,
// Doxygen documentation generator set
"doxdocgen.file.copyrightTag": [
"@copyright Copyright (c) {year} XX通信公司"
],
"doxdocgen.file.customTag": [
"@par 修改日志:",
"",
"Date Version Author Description",
" {date} 1.0 wangh 内容",
"
",
],
"doxdocgen.file.fileOrder": [
"file",
"brief",
"author",
"version",
"date",
"empty",
"copyright",
"empty",
"custom"
],
"doxdocgen.file.fileTemplate": "@file {name}",
"doxdocgen.file.versionTag": "@version 1.0",
"doxdocgen.generic.authorEmail": "[email protected]",
"doxdocgen.generic.authorName": "wangh",
"doxdocgen.generic.authorTag": "@author {author} ({email})",
"doxdocgen.generic.order": [
"brief",
"tparam",
"param",
"return"
],
"doxdocgen.generic.paramTemplate": "@param{indent:8}{param}{indent:25}My Param doc",
"doxdocgen.generic.returnTemplate": "@return {type} ",
"doxdocgen.generic.splitCasingSmartText": true,
}
{
// Doxygen documentation generator set
// 文件注释：版权信息模板
"doxdocgen.file.copyrightTag": [
"@copyright Copyright (c) {year} XX通信公司"
],
// 文件注释：自定义模块，这里我添加一个修改日志
"doxdocgen.file.customTag": [
"@par 修改日志:",
"",
"Date Version Author Description",
" {date} 1.0 wangh 内容",
"
",
],
// 文件注释的组成及其排序
"doxdocgen.file.fileOrder": [
"file", // @file
"brief", // @brief 简介
"author", // 作者
"version", // 版本
"date", // 日期
"empty", // 空行
"copyright",// 版权
"empty",
"custom" // 自定义
],
// 下面时设置上面标签tag的具体信息
"doxdocgen.file.fileTemplate": "@file {name}",
"doxdocgen.file.versionTag": "@version 1.0",
"doxdocgen.generic.authorEmail": "[email protected]",
"doxdocgen.generic.authorName": "wangh",
"doxdocgen.generic.authorTag": "@author {author} ({email})",
// 日期格式与模板
"doxdocgen.generic.dateFormat": "YYYY-MM-DD",
"doxdocgen.generic.dateTemplate": "@date {date}",
// 根据自动生成的注释模板（目前主要体现在函数注释上）
"doxdocgen.generic.order": [
"brief",
"tparam",
"param",
"return"
],
"doxdocgen.generic.paramTemplate": "@param{indent:8}{param}{indent:25}My Param doc",
"doxdocgen.generic.returnTemplate": "@return {type} ",
"doxdocgen.generic.splitCasingSmartText": true,
}
在函数前面输入/**回车以后
/**
* @brief
* @param data My Param doc
* @param left_1 My Param doc
* @param right_1 My Param doc
* @param left_2 My Param doc
* @param right_2 My Param doc
*/
void merge(vector& data, int left_1, int right_1, int left_2,
int right_2)
之后可以使用Doxygen生成文档
Doxygen实际使用
本人习惯使用Doxygen的可视化工具，具体教程为
link
类图如下
