一款常用文档生成工具:Doxygen
关注+星标公众号,不错过精彩内容
来源 | 简书
编排 | strongerHuang
程序员的很多文档,特别是有代码的文档,绝大部分都是由一款文档生成工具【Doxygen】生成。
什么是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、基本使用
图形工具的基本使用如下图所示,有非常多的配置选项,这里我们只填入必要的配置,其它配置都用默认值。
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
------------ END ------------
●专栏《嵌入式工具》
●专栏《嵌入式开发》
●专栏《Keil教程》
●嵌入式专栏精选教程
关注公众号回复“加群”按规则加入技术交流群,回复“1024”查看更多内容。
点击“阅读原文”查看更多分享。
一款常用文档生成工具:Doxygen相关推荐
- 文档生成工具-Doxygen使用方法以及注释规则
最近接触了一款程序 文档生成工具-Doxygen.在网上一搜索原来这么多人知道,打算把它的使用做一个总结,以及其注释的规则. 概述: Doxygen是一种开源跨平台的,以类似JavaDoc风格描述的文 ...
- mysql 文档生成器_最好用的数据库文档生成工具
一 前言 本文介绍一些比较流行的数据库文档生成工具,什么是数据库文档? 其实在工作中进行项目交付的时候经常用到:简单来说数据库文档就是对整个数据库设计说明的文档,比如使用了哪个数据库,每张表的字段,类 ...
- java 接口文档工具_一款Java基于注释的接口文档生成工具
一. 痛点 你还在手动维护接口文档嘛,花一个下午不停的复制粘贴代码里面的注释 接口字段变动,还得去更新文档,更新不及时导致文档不同步 或者你使用了swagger之类的基于注解,依靠运行时的文档工具,看 ...
- apiDoc 一款很不错api文档生成工具
apiDoc 一款很不错api文档生成工具,在开发接口的时候,需要给同事看相应的接口文档.给大家推荐一个生成文档的工具--apiDoc,最后生成的文档以网页的形式发布,方便快捷,便于阅读. 创建项目目 ...
- Doxygen自动文档生成工具在Eclipse中的集成及使用举例
你有为软件编写说明文档的苦恼吗?当别人甩给你一个庞大的系统,让你根据里面的代码注释理解后写出一份完整的开发文档,你会怎么办?一个个的看代码 然后耗时N天来写吗?这既是一份苦差事也极其耗时,有没有更好的 ...
- spring-boot 一款无侵入型,轻量级的接口文档生成工具apiggs
spring-boot 一款无侵入型,轻量级的接口文档生成工具apiggs 名字叫:apiggs 使用只需两步,先把插件代码引入pom文件,然后编译打包即可 之后项目的target目录下,就会多出一个 ...
- Doxygen文档生成工具
Doxygen代码文档生成工具 文章目录 Doxygen代码文档生成工具 Doxygen Doxygen的注释 vscode插件 Doxygen实际使用 Doxygen 根据百度百科说法,Doxyge ...
- 分享一款非常棒的数据库文档生成工具,可导出md、excel等格式
1.背景 因为要给朋友项目补数据库文档,文档中需要填写数据库表结构等信息. 找了一个开源的.非常棒的数据库文档生成工具,可以导出word.excel(可编辑).md等格式..亲测,很棒,分享给大家.. ...
- 数据库文档生成工具V1.0
这是一款基于C#开发语言编写的数据库文档生成工具,主要实现了 SQlServer+MYsql 数据库表结构说明文档的生成,并且支持 SQLServer 数据库的备份功能,主要可以把数据库的表以及表的详 ...
最新文章
- 【文本分类】基于改进TF-IDF特征的中文文本分类系统
- 人工智能产业政策与行业应用场景-备课资料
- 使用hexo搭建个人博客
- video自动全屏播放
- 从零开始学视觉Transformer(5):如何训练ViT模型、DeiT算法解析
- ubuntu开机报错 system program problem detected
- 第一次更名为OpenInfra的“她”,给我们带来了哪些惊喜?| 技术头条
- 2020年泰国物联网五大部门中 制造业物联网市值为13亿美元
- CakePHP 3.7.6 发布,PHP 快速开发框架
- TiDB RC1 Release
- Python快速下载M3U8电影
- navicat导数据速度_快速解决mysql导数据时,格式不对、导入慢、丢数据的问题
- azkaban build报错
- 用文字总结出计算机组装步骤,项目教学法在《计算机组装与维护》中的运用与反思(杜燕)...
- 微信公众号订阅通知(go+vue)
- 在电脑双屏使用时,搜狗输入法在别的屏幕(转)
- new Date() 获取当前时间对象(getFullYear、getMonth、getDate、getHours、getMinutes、getSeconds、getDay、getTime)
- 少儿机器人教育在国内的情况
- 事件A和B之间相互独立与互不相容的理解
- [韩国KBS][伟大的遗产]
热门文章
- WR703n安装openwrt做打印服务器
- 无论是狗粮还是降落伞,反正WeLink来了……
- 发哥莫慌!这56亿让区块链帮你搞定
- MyEclipse热部署----使用工具 JRebel
- 李俊计算机哈佛大学,李俊教授个人主页
- R语言ERROR: compilation failed for package ‘****‘
- 关于提高浏览器渲染页面速度的建议
- 【产业互联网周报】任正非再谈“云战略”;上汽集团进军芯片产业;Salesforce 2021财年净利润40.72亿美元...
- 西电杨宗凯调研计算机学院,西安电子科技大学校长杨宗凯到网络与继续教育学院调研指导工作...
- excel表格经纬度同表格分成经度纬度两个表格