Doxygen文档生成工具

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 修改日志:",
        "<table>",
        "<tr><th>Date       <th>Version <th>Author  <th>Description",
        "<tr><td>{date} <td>1.0     <td>wangh     <td>内容",
        "</table>",
    ],
    "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": "wanghuan3037@fiberhome.com",
    "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 修改日志:",
        "<table>",
        "<tr><th>Date       <th>Version <th>Author  <th>Description",
        "<tr><td>{date} <td>1.0     <td>wangh     <td>内容",
        "</table>",
    ],
    // 文件注释的组成及其排序
    "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": "wanghuan3037@fiberhome.com",
    "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<int>& data, int left_1, int right_1, int left_2,
           int right_2)

之后可以使用Doxygen生成文档

Doxygen实际使用

本人习惯使用Doxygen的可视化工具，具体教程为

link

类图如下