0
  • 聊天消息
  • 系统消息
  • 评论与回复
登录后你可以
  • 下载海量资料
  • 学习在线课程
  • 观看技术视频
  • 写文章/发帖/加入社区
创作中心

完善资料让更多小伙伴认识你,还能领取20积分哦,立即完善>

3天内不再提示

一款文档生成工具:Doxygen生成

strongerHuang 来源:简书 作者:strongerHuang 2022-04-27 09:15 次阅读

程序员的很多文档,特别是有代码的文档,绝大部分都是由一款文档生成工具【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、基本使用 图形工具的基本使用如下图所示,有非常多的配置选项,这里我们只填入必要的配置,其它配置都用默认值。

42e1a25e-c5c2-11ec-bce3-dac502259ad0.jpg

doxywizard使用步骤

42ef3644-c5c2-11ec-bce3-dac502259ad0.jpg

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 用弧度制或角度制表示都行,字符串必须用'�'表示结束
param[out] res 是输出参数,用于保存sin运算的结果


eturn 错误码,0表示成功,其它表示失败

	odo 在xxx的情况下存在BUG,预计下一版本修复
*/
intsin(char*a,double*res);

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

42fd5422-c5c2-11ec-bce3-dac502259ad0.jpg

HTML界面

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

430ad3c2-c5c2-11ec-bce3-dac502259ad0.jpg

保存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等等。

4318b8ac-c5c2-11ec-bce3-dac502259ad0.jpg

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

4327f9a2-c5c2-11ec-bce3-dac502259ad0.jpg

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

433668c0-c5c2-11ec-bce3-dac502259ad0.jpg


2.Doxygen官方不支持的语言 以Lua语言为例,它的代码是长这样的:
-- file lmath.h

--[[    用于求一个角度的sin值,输入是字符串以便同时支持弧度制和角度制表示    

li 弧度制用pi表示,例如:2pi表示一圈、0.5pi表示直角    

li 角度制用d结尾,例如:360d表示一圈、90d表示直角    

li 输入也可以是数值,例如:输入3.14159大约表示180度

    param a 字符串类型,表示角度,用弧度制或角度制表示都行
    
eturn 返回sin运算的结果

    	odo 在xxx的情况下存在BUG,预计下一版本修复--]]function sin(a)    return 1.123end
可以看到Lua的语法既不像C也不像Python。 审核编辑 :李倩

声明:本文内容及配图由入驻作者撰写或者入驻合作网站授权转载。文章观点仅代表作者本人,不代表电子发烧友网立场。文章及其配图仅供工程师学习之用,如有内容侵权或者其他违规问题,请联系本站处理。 举报投诉
  • 开源
    +关注

    关注

    3

    文章

    2964

    浏览量

    41605
  • C++
    C++
    +关注

    关注

    21

    文章

    2061

    浏览量

    72848

原文标题:一款常用文档生成工具:Doxygen

文章出处:【微信号:strongerHuang,微信公众号:strongerHuang】欢迎添加关注!文章转载请注明出处。

收藏 人收藏

    评论

    相关推荐

    NVIDIA生成式AI研究实现在1秒内生成3D形状

    NVIDIA 研究人员使 LATTE3D (一款最新文本转 3D 生成式 AI 模型)实现双倍加速。
    的头像 发表于 03-27 10:28 113次阅读
    NVIDIA<b class='flag-5'>生成</b>式AI研究实现在1秒内<b class='flag-5'>生成</b>3D形状

    【鸿蒙】NAPI 框架生成工具实现流程

    NAPI 框架生成工具 可以根据用户指定路径下的 ts(typescript)接口文件一键生成 NAPI 框架代码、业务代码框架、GN 文件等。在开发 JS 应用与 NAPI 间接口时,底层框架
    的头像 发表于 02-28 17:00 167次阅读
    【鸿蒙】NAPI 框架<b class='flag-5'>生成</b><b class='flag-5'>工具</b>实现流程

    沃尔玛推出生成式人工智能工具

    在拉斯维加斯举办的2024年消费电子展上,全球最大的零售商沃尔玛发布了一款最新的AI技术产品。该公司推出了一种生成式人工智能工具,这一工具将改变传统的购物搜索方式。
    的头像 发表于 01-10 14:58 1064次阅读

    labview生成专业的测试报表工具

    Labview软件免费的报表生成工具
    发表于 12-21 09:57 1次下载

    能够生成java文档注释的命令

    生成Java文档注释的命令是通过使用Java的自带工具Javadoc来实现的。Javadoc是一个能够从源代码中提取注释并生成文档工具。下
    的头像 发表于 11-29 14:12 267次阅读

    用MCUXpresso调试其它工具生成的项目

    用MCUXpresso调试其它工具生成的项目
    的头像 发表于 10-31 16:42 226次阅读
    用MCUXpresso调试其它<b class='flag-5'>工具</b>链<b class='flag-5'>生成</b>的项目

    如何使用Keil生成汇编文档

    如何使用Keil IDE环境中生成汇编文档使用Keil IDE环境中生成汇编文档
    发表于 10-19 07:31

    如何一键生成mybatisplus

    我在详细的讲解一下官方的文档。 2、添加依赖 MyBatis-Plus 从 3.0.3 之后移除了代码生成器与模板引擎的默认依赖,需要手动添加相关依赖。 ①、添加代码生成器依
    的头像 发表于 09-25 14:23 370次阅读
    如何一键<b class='flag-5'>生成</b>mybatisplus

    基于Go语言的反弹Shell命令生成工具简介

    RevShell 是一个基于Go语言的反弹Shell命令生成工具,旨在帮助安全研究人员和渗透测试人员在需要与目标主机建立反向连接时快速生成相应的Shell代码。
    发表于 08-25 09:45 405次阅读
    基于Go语言的反弹Shell命令<b class='flag-5'>生成</b><b class='flag-5'>工具</b>简介

    Arm RAN加速库的参考文档

    本书包含Arm RAN加速库(ArmRAL)的参考文档。这本书是由使用Doxygen的源代码生成的。
    发表于 08-10 07:08

    MBD的Simulink使用技巧:Simulink代码生成的基本概念(1)

    MATLAB/Simulink中一共提供三个代码生成工具
    的头像 发表于 07-13 15:11 1293次阅读
    MBD的Simulink使用技巧:Simulink代码<b class='flag-5'>生成</b>的基本概念(1)

    コード生成プラグイン学習ガイド

    コード生成プラグイン学習ガイド
    发表于 07-12 19:19 0次下载
    コード<b class='flag-5'>生成</b>プラグイン学習ガイド

    什么是生成式AI?生成式AI的四大优势

    生成式AI是一种特定类型的AI,专注于生成新内容,如文本、图像和音乐。这些系统在大型数据集上进行训练,并使用机器学习算法生成与训练数据相似的新内容。这在各种应用程序中都很有用,比如创建艺术、音乐和聊天机器人
    发表于 05-29 14:12 2358次阅读

    コード生成プラグイン学習ガイド

    コード生成プラグイン学習ガイド
    发表于 05-15 20:26 0次下载
    コード<b class='flag-5'>生成</b>プラグイン学習ガイド

    芯易荟发布首款领域专用处理器生成工具FARMStudio

    芯易荟(ChipEasy)于4月12日举办发布会,正式发布首款自主研发的领域专用处理器生成工具FARMStudioTM 。作为芯易荟自研的第一款重磅产品,FARMStudioTM 是全球首款采用
    发表于 04-12 18:16 850次阅读
    芯易荟发布首款领域专用处理器<b class='flag-5'>生成</b><b class='flag-5'>工具</b>FARMStudio