程序员在撰写文档时，尤其是带有代码的文档，很多时候都会使用一款名为Doxygen的文档生成工具来生成。

那么，什么是Doxygen呢？

Doxygen是一个用于从源代码中提取特定注释的工具，从而生成文档的程序文件生产工具。在程序编写过程中，我们通常会写一些注释，但是对于其他人来说，要直接研究这些注释可能会很棘手。大多数有用的注释都是针对函数、类等的说明。因此，如果能够根据程序本身的结构对注释进行处理和重新整理，生成一个纯参考手册，对于后面使用你的代码的人来说，将减少很多负担。但是，反过来说，整理文件的工作对于你自己来说却是一项沉重的负担。

总之，Doxygen是一个广受欢迎的文档生成工具，而且是开源的免费工具。它使用非常简单，可以提取C++、Java、Objective-C、Python、IDL、PHP、C#等语言的注释，并生成文档。

使用Doxygen可分为两个主要步骤。首先是编写特定格式的注释，其次是利用Doxygen工具生成文档。

生成文档使用教程

1、安装

在Linux下可以通过apt install doxygen安装命令行工具，然后用apt install doxygen-gui安装图形界面。

对Linux用户来说，命令行工具可以通过doxygen命令运行，而图形界面可以通过doxywizard命令运行。

Windows 用户的下载地址：

http://www.doxygen.nl/download.html

2、基本使用

图形工具的基本使用如下图所示，有非常多的配置选项，这里我们只填入必要的配置，其它配置都用默认值。

doxywizard使用步骤

doxywizard使用步骤

工作目录如下：

.
├── out
└── src
    └── math.h

其中math.h代码如下：

/*! \file math.h */

/*!
    用于求一个角度的sin值，输入是字符串以便同时支持弧度制和角度制表示
    \li 弧度制用pi表示，例如：2pi表示一圈、0.5pi表示直角
    \li 角度制用d结尾，例如：360d表示一圈、90d表示直角
    \li 输入也可以是数值，例如：输入3.14159大约表示180度

    \param a 用弧度制或角度制表示都行，字符串必须用'\0'表示结束
    \param[out] res 是输出参数，用于保存sin运算的结果

    \return 错误码，0表示成功，其它表示失败

    \todo 在xxx的情况下存在BUG，预计下一版本修复
*/
int sin(char *a, double *res);

Doxygen生成的HTML会放到out目录下，生成的HTML如下图所示。

HTML界面

3、保存配置

上面我们配置了一些选项，也成功生成了HTML文档。我们希望下次代码改动后能够继续沿用上次配置，那么我们可以把这些配置保存成Doxyfile文件，如下图所示。

保存Doxyfile配置文件

4、命令行运行Doxygen

有了配置文件后我们完全可以通过命令行来生成API文档，假设配置文件名为Doxyfile，那么我们只需要执行doxygen /path/to/Doxyfile即可生成API文档。

通过命令行生成文档有许多好处，其中最主要的好处就是：能够集成到持续集成之类的自动化系统中。

为代码编写注释

1.什么样的注释会被Doxygen识别？

Doxygen能识别这几种风格的注释：

/**
 * ... text ...
 */

/*!
 * ... text ...
 */

///
/// ... text ...
///

//!
//!... text ...
//!

文件的开头必须有文件注释，否则该文件不会被识别：

/*! \file math.h */

2.注释怎么写

这里建议参考官网例子。

https://www.doxygen.nl/manual/doxygen_usage.html

为其它编程语言生成注释

Doxygen主要支持C语言，其它语法跟C差不多的语言（如：C++/C#/PHP/Java）也能够支持，我们称这类语言为「C语系语言」。而哪些跟C语法差异较大的语言叫做「非C语系语言」。

对于大多非C语系语言，Doxygen都是支持的，Doxygen原生支持这些语言：IDL、Java、Javascript、C#、C、C++、D、PHP、Objective-C、Python、Fortran、VHDL。

万一项目需要的语言（例如：Lua）Doxygen官方并不支持，那么只能自行编写「第三方语言扩展」来支持了。

1.Doxygen官方支持的语言

见下图，文件名符合FILE_PATTERNS都会被处理。其中包括了.c、.h、.py等等。

如果我们的扩展名并不在FILE_PATTERNS内，那么可以加上去。例如我们项目下的所有.ccc文件，其实是C语言代码（这很奇葩，举个例子而已）。那我们可以编辑Doxyfile配置文件满足这一需求，需要2个步骤。

(1) 在FILE_PATTERNS中添加*.ccc，如下图：

(2) 在EXTENSION_MAPPING中添加映射规则ccc=C，如下图，语法是ext=language，其中language可以取的值有：IDL、Java、Javascript、C#、C、C++、D、PHP、Objective-C、Python、Fortran、VHDL。

2.Doxygen官方不支持的语言

以Lua语言为例，它的代码是长这样的：

-- \file lmath.h

--[[
    用于求一个角度的sin值，输入是字符串以便同时支持弧度制和角度制表示
    \li 弧度制用pi表示，例如：2pi表示一圈、0.5pi表示直角
    \li 角度制用d结尾，例如：360d表示一圈、90d表示直角
    \li 输入也可以是数值，例如：输入3.14159大约表示180度

    \param a 字符串类型，表示角度，用弧度制或角度制表示都行

    \return 返回sin运算的结果

    \todo 在xxx的情况下存在BUG，预计下一版本修复
--]]
function sin(a)
    return 1.123
end

可以看到Lua的语法既不像C也不像Python。

本文就分享到这里，更详细的使用教程可以查看官方文档：

https://www.doxygen.nl/manual/doxygen_usage.html

以上就是良许教程网为各位朋友分享的Linu系统相关内容。想要了解更多Linux相关知识记得关注公众号“良许Linux”，或扫描下方二维码进行关注，更多干货等着你 ！