程序员的很多文档,特别是有代码的文档,绝大部分都是由一款文档生成工具【Doxygen】生成。

什么是Doxygen?

Doxygen 是一个程序的文件产生工具,可将程序中的特定批注转换成为说明文件。通常我们在写程序时,或多或少都会写上批注,但是对于其它人而言,要直接探索程序里的批注,与打捞铁达尼号同样的辛苦。
大部分有用的批注都是属于针对函式,类别等等的说明。所以,如果能依据程序本身的结构,将批注经过处理重新整理成为一个纯粹的参考手册,对于后面利用你的程序代码的人而言将会减少许多的负担。不过,反过来说,整理文件的工作对于你来说,就是沉重的负担。
简而言之,Doxgen就是大名鼎鼎的文档生成工具,而且是免费开源的,它使用非常方便,能提取C++,Java,Objective-C,Python,IDL,PHP,C#等语言的注释,从而生成文档。
Doxygen 的使用可分为两大部分。首先是特定格式的批注撰写,第二便是利用Doxygen的工具来生成文档。
在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配置文件

有了配置文件后我们完全可以通过命令行来生成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.123end

可以看到Lua的语法既不像C也不像Python。
本文就分享到这里,更详细的使用教程可以查看官方文档:

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

转载于:https://mp.weixin.qq.com/s/XfaP6DF5G6lgXRJo8XAV2Q


如果只有一个没有注释的文件文件,一个没有注释的函数

image-20220429174231889

#include <stdio.h>

int main(void) {
    printf("Hello World!\n");
}

最后产生的文档则是啥也没有。


还是一个源文件,文件有注释,函数也有两个,函数也都有注释

/**
  * @file     	main.c
  * @author   	JonesLee
  * @email   	Jones_Lee3@163.com
  * @version	V4.01
  * @date    	07-DEC-2017
  * @license  	GNU General Public License (GPL)  
  * @brief   	Universal Synchronous/Asynchronous Receiver/Transmitter 
  * @detail		detail
  * @attention
  *  This file is part of OST.                                                  \n                                                                  
  *  This program is free software; you can redistribute it and/or modify 		\n     
  *  it under the terms of the GNU General Public License version 3 as 		    \n   
  *  published by the Free Software Foundation.                               	\n 
  *  You should have received a copy of the GNU General Public License   		\n      
  *  along with OST. If not, see <http://www.gnu.org/licenses/>.       			\n  
  *  Unless required by applicable law or agreed to in writing, software       	\n
  *  distributed under the License is distributed on an "AS IS" BASIS,         	\n
  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  	\n
  *  See the License for the specific language governing permissions and     	\n  
  *  limitations under the License.   											\n
  *   																			\n
  * @htmlonly 
  * <span style="font-weight: bold">History</span> 
  * @endhtmlonly 
  * Version|Auther|Date|Describe
  * ------|----|------|-------- 
  * V3.3|Jones Lee|07-DEC-2017|Create File
  * <h2><center>&copy;COPYRIGHT 2017 WELLCASA All Rights Reserved.</center></h2>
  */  

#include <stdio.h>

/**
 * @brief hhhhh,this is a test file.
 * 
 * @return int 
 */
int add(int a, int b) {
    return a+b;
}

int main(void) {
    printf("Hello World!\n");
}

最后生成的文档如下图:

image-20220429180227347

image-20220429180150214

https://raw.githubusercontent.com/xkyvvv/blogpic3/main/image-20220429181945825.png


有多个源文件,每个文件有多个函数

在这里插入图片描述

main.c

/**
  * @file     	main.c
  * @author   	JonesLee
  * @email   	Jones_Lee3@163.com
  * @version	V4.01
  * @date    	07-DEC-2017
  * @license  	GNU General Public License (GPL)  
  * @brief   	Universal Synchronous/Asynchronous Receiver/Transmitter 
  * @detail		detail
  * @attention
  *  This file is part of OST.                                                  \n                                                                  
  *  This program is free software; you can redistribute it and/or modify 		\n     
  *  it under the terms of the GNU General Public License version 3 as 		    \n   
  *  published by the Free Software Foundation.                               	\n 
  *  You should have received a copy of the GNU General Public License   		\n      
  *  along with OST. If not, see <http://www.gnu.org/licenses/>.       			\n  
  *  Unless required by applicable law or agreed to in writing, software       	\n
  *  distributed under the License is distributed on an "AS IS" BASIS,         	\n
  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  	\n
  *  See the License for the specific language governing permissions and     	\n  
  *  limitations under the License.   											\n
  *   																			\n
  * @htmlonly 
  * <span style="font-weight: bold">History</span> 
  * @endhtmlonly 
  * Version|Auther|Date|Describe
  * ------|----|------|-------- 
  * V3.3|Jones Lee|07-DEC-2017|Create File
  * <h2><center>&copy;COPYRIGHT 2017 WELLCASA All Rights Reserved.</center></h2>
  */  

#include <stdio.h>

/**
 * @brief hhhhh,this is a test file.
 * 
 * @return int 
 */
int add(int a, int b) {
    return a+b;
}

/**
 * @brief sub function
 * 
 * @return int 
 */
int sub(int a, int b) {
    return a-b;
}

/**
 * @brief xkyzzz
 * 
 * @return int
 */
int main(void) {
    printf("Hello World!\n");
}

module.c

/**
  * @file     	module.c
  * @author   	xky
  * @email   	Jones_Lee3@163.com
  * @version	V4.01
  * @date    	07-DEC-2017
  * @license  	GNU General Public License (GPL)  
  * @brief   	Universal Synchronous/Asynchronous Receiver/Transmitter 
  * @detail		detail
  * @attention
  *  This file is part of OST.                                                  \n                                                                  
  *  This program is free software; you can redistribute it and/or modify 		\n     
  *  it under the terms of the GNU General Public License version 3 as 		    \n   
  *  published by the Free Software Foundation.                               	\n 
  *  You should have received a copy of the GNU General Public License   		\n      
  *  along with OST. If not, see <http://www.gnu.org/licenses/>.       			\n  
  *  Unless required by applicable law or agreed to in writing, software       	\n
  *  distributed under the License is distributed on an "AS IS" BASIS,         	\n
  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  	\n
  *  See the License for the specific language governing permissions and     	\n  
  *  limitations under the License.   											\n
  *   																			\n
  * @htmlonly 
  * <span style="font-weight: bold">History</span> 
  * @endhtmlonly 
  * Version|Auther|Date|Describe
  * ------|----|------|-------- 
  * V3.3|Jones Lee|07-DEC-2017|Create File
  * <h2><center>&copy;COPYRIGHT 2017 WELLCASA All Rights Reserved.</center></h2>
  */  
 

/**
 * @brief 
 * 
 */
void mFun1(void)
{
    ;
}

/**
 * @brief 
 * 
 */
void mFun2(void)
{
    ;
}

生成文档如下图:

image-20220429183830257

https://raw.githubusercontent.com/xkyvvv/blogpic3/main/image-20220429183938826.png

image-20220429184003292

image-20220429184022485

image-20220429184052826

image-20220429184109931

通过上面这些测试,我们应该可以知道如何去使用这个软件。下面我以一个实际项目的源码来测试一下。

测试的代码是RT-Thread的源码,地址:https://github.com/RT-Thread/rt-thread

源码目录:

在这里插入图片描述

生成文档如下图:

image-20220429193525371

Logo

华为云1024程序员节送福利,参与活动赢单人4000元礼包,更有热门技术干货免费学习

更多推荐