Doxygen 文档生成工具使用教程

程序员考拉

共 1746字,需浏览 4分钟

 ·

2020-11-27 13:58

公众号关注 “GitHub今日热榜
设为 “星标”,带你挖掘更多开发神器!





一、什么是Doxygen?


Doxygen 是一个程序的文件产生工具,可将程序中的特定批注转换成为说明文件。通常我们在写程序时,或多或少都会写上批注,但是对于其它人而言,要直接探索程序里的批注,与打捞铁达尼号同样的辛苦。大部分有用的批注都是属于针对函式,类别等等的说明。所以,如果能依据程序本身的结构,将批注经过处理重新整理成为一个纯粹的参考手册,对于后面利用你的程序代码的人而言将会减少许多的负担。不过,反过来说,整理文件的工作对于你来说,就是沉重的负担。


简而言之,Doxgen就是大名鼎鼎的文档生成工具,而且是免费开源的,它使用非常方便,能提取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、基本使用


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




工作目录如下:


.
├── 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如下图所示。



3、保存配置


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



4、命令行运行Doxygen


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


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


三、为代码编写注释


什么样的注释会被Doxygen识别?


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


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


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


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

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


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


/*! \file math.h */


更详细的使用教程可以查看官方文档:


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








关注GitHub今日热榜,专注挖掘好用的开发工具,致力于分享优质高效的工具、资源、插件等,助力开发者成长!







点个在看 你最好看










浏览 32
点赞
评论
收藏
分享

手机扫一扫分享

分享
举报
评论
图片
表情
推荐
点赞
评论
收藏
分享

手机扫一扫分享

分享
举报