电子工程师技术服务社区
公告
登录
|
注册
首页
技术问答
厂商活动
正点原子
板卡试用
资源库
下载
文章
社区首页
文章
干货|教你使用Doxygen制作出漂亮程序文档
分 享
扫描二维码分享
干货|教你使用Doxygen制作出漂亮程序文档
Doxygen
注释
程序文档
果果小师弟
关注
发布时间: 2021-08-20
丨
阅读: 2511
**摘要**:不知道大家有没有把自己的代码整理成文档的习惯,有没有给自己的代码一个非常漂亮的注释,就像下图这样。 ![8051-ELL库](https://img-blog.csdnimg.cn/0210589615204f0ca2b6a0dc48a80546.png) 如果你写了一个结构体或者枚举是否也是这样注释的? ![8051-ELL库](https://img-blog.csdnimg.cn/217f08984add422e8a3f7bb91e7f7be8.png) 如果每个人的注释都是这样写的话,被人怎么可能看不懂你的代码?如果你不是这样的话,你就必须要看这篇文章了。 等等,别走!还有~ 你是不是也看过很多说明文档,比如下面这样的关于**STM32标准外设驱动文档**。你有没有想象过自己的代码也是可以这样打包成这样一个非常漂亮的文档的? ![STM32F10x_StdPeriph_Driver_3.5.0(中文版).chm](https://img-blog.csdnimg.cn/9e427a906d5f42e09225bd171d70592b.png) ![STM32F10x_StdPeriph_Driver_3.5.0(中文版).chm](https://img-blog.csdnimg.cn/f4ac8946ca494e109c603734061b4ce5.png) 今天就教大家如何给**写注释**,如何写出**漂亮规范的注释**,让人看着心旷神怡,透人心脾。如何写出规范的说明文档,让人看了**直呼内行,给你点赞**! **Doxygen能将程序中的特定批注转换成为说明文件**。它可以依据程序本身的结构,将程序中按规范注释的批注经过处理生成一个纯粹的**参考手册**,通过提取代码结构或借助自动生成的包含依赖图、继承图)以及协作图来可视化文档之间的关系,Doxygen生成的帮助文档的格式可以是CHM、RTF、PostScript、PDF、HTML等。 微软出品的HTML Help WorkShop是制作CHM文件的最佳工具,它能将HTML文件编译生成CHM文档。Doxygen软件默认生成HTML文件或Latex文件,我们要通过HTML生成CHM文档,需要先安装HTML Help WorkShop软件,并在Doxygen中进行关联即可。 下面将按照这张思维导图来讲述如何安装软件,以及如何写单片机注释和最终如何导出文档。 ![本文思维导图](https://img-blog.csdnimg.cn/60e3568bb6e04a8ea64ecc6c818097b5.png) # 1、windows安装doxygen 首先在官网下载doxygen,网址:[https://www.doxygen.nl/download.html](https://www.doxygen.nl/download.html) ![](https://img-blog.csdnimg.cn/e53505cdc4b541b19d7849864992d32c.png) 下载完成后傻瓜式一步一步安装就可以了。安装完成后在开始栏点击Doxywizard就可以打开软件了。 ![](https://img-blog.csdnimg.cn/9c1f5186a9ad4b83aa8badec4da9af5e.png) # 2、Linux安装doxygen 这里我是使用的是ubuntu虚拟机,使用`sudo apt-get install doxygen`就可以安装了。 ![](https://img-blog.csdnimg.cn/6c2b008b3c81434cb51b59ac1d5d120a.png) 安装完成后在命令行输入`doxygen`,如果出现帮助信息,说明安装成功,如果出现`command not font`则表明安装失败。之后使用`sudo apt-get install doxygen-gui`安装gui,就可以像windows那样使用图形化操作了。安装完成后使用`doxygenwizard`命令就可以打开doxygen了。 ```bash sudo apt-get install doxygen sudo apt-get install doxygen-gui ``` ![Linux ubuntu16.04 TLS](https://img-blog.csdnimg.cn/88c2e681511d4a548125fb60e9324e8a.png) 如何在`ubuntu`上创建快捷方式,自行百度。 # 3、MacOS安装doxygen 首先在官网下载`MacOS`版本的安装包。下载完成后,直接把他拖到`application`上面就可以了。 ![](https://img-blog.csdnimg.cn/e6ad0467411045119b7b42573016fb21.png) ![MacOS](https://img-blog.csdnimg.cn/e573d7c9be8b41398dc2a78c03382b16.png) # 4、Doxygen语法简介 所谓`Doxygen`语法就是在写程序注视时候按照`Doxygen`语法规则来写注释。只有按照标准的注释规则来写注释,生成的文档才会非常偏亮,否则乱七八糟的。 ## 1.特殊命令简介 命令| 字段名| 语法| -------- | -----|------| @file | 文件名| file [< name >] | @brief | 简介|brief { brief description }| @author | 作者|author { list of authors }| @mainpage | 主页信息| mainpage [(title)] | @date | 年-月-日|date { date description }| @author |版本号|version { version number }| @copyright| 版权|copyright { copyright description }| @param | 参数|param [(dir)] < parameter-name> { parameter description }| @return | 返回| return { description of the return value } | @retval | 返回值|retval
{ description }| @bug | 漏洞|bug { bug description }| @details| 细节| details { detailed description }| @pre | 前提条件|pre { description of the precondition }| @see | 参考|see { references }| @link | 连接(与@see类库,{@link www.google.com})| link < link-object> | @throw | 异常描述|throw < exception-object> { exception description }| @todo | 待处理|todo { paragraph describing what is to be done }| @warning| 警告信息| warning { warning message }| @deprecated | 弃用说明。可用于描述替代方案,预期寿命等|deprecated { description }| @example | 弃用说明。可用于描述替代方案,预期寿命等|deprecated { description }| 以上是写注释是可以加上的,但是实际操作中,并不需要这么多参数。 ## 2.文件注释 一般放在文件开头 ```c /@@** * @file 文件名 * @brief 简介 * @details 细节 * @author 作者 * @version 版本号 * @date 年-月-日 * @copyright 版权 */ ``` 示例 ![ ](https://img-blog.csdnimg.cn/2ea986e4003b4154b12390bca63898cf.png) ## 3.结构体注释 ```c /@@** * @brief 类的详细描述 */ ``` 示例 ![ ](https://img-blog.csdnimg.cn/246c241878e64600a8b309f01c397974.png) ## 4.函数注释 ```c /@@** * @brief 函数描述 * @param 参数描述 * @return 返回描述 * @retval 返回值描述 */ ``` 实例 ![](https://img-blog.csdnimg.cn/6aa9995ca3ae487a8862ca368910ff72.png) ## 5.常量/变量注释 一般常量/变量可以有两种形式: * 常量/变量上一行注释 * 常量/变量后注释 ```bash //定义一个整型变量a int a; /@@** * @brief 定义一个整型变量a */ int a; ``` ```c int a; /@@*!< 定义一个整型变量a */ int a; /@@**< 定义一个整型变量a */ int a; //!< 定义一个整型变量a int a; ///< 定义一个整型变量a ``` # 5、使用Doxygen软件 上面说了半天就是想主要是让大家规范注释,然后使用Doxygen软件生成文档后会规范一些。我们以keil软件为例,使用Doxygen软件把我们的keil工程代码生成一份文档,这个文档包含了所有的函数与结构体,以及我们定义的所有函数,这样别人在看你的代码时就方便多了。 1、打开Doxygen软件。 ![](https://img-blog.csdnimg.cn/3333126d0e234cb69a8eb2e547d5a7fc.png) 2、选择运行`doxygen`的工作目录,就是你的keil工程在哪一个文件夹,这里就定位到那个文件夹。 ![doxygen 的工作目录](https://img-blog.csdnimg.cn/40816181e4dd4d7096a7dc8fa4a286af.png) 2、接着填写一些生成文档的一些信息,包括文档名称、简介、版本、源码文件路径、生成的文档路径。 ![ ](https://img-blog.csdnimg.cn/6a4de1604f9d46ac93f782ea083ce30f.png) 3.选择生成文档的格式,默认可以生成html和tatex格式的。 ![ ](https://img-blog.csdnimg.cn/2bc8beff47924ba499d5125c769a0a29.png) 4.最后再run选项卡中点击Run doxygen就可以生成了。 ![](https://img-blog.csdnimg.cn/f5eda5135b1441f7b33533c720fa6461.png) 5.在生成的目录中找到`index.html`文件打开即可。 ![](https://img-blog.csdnimg.cn/3e3955fd72a64115855c3e77bb2f0b7b.png) ![浏览器打开](https://img-blog.csdnimg.cn/9149e7581f4c4f91a24eef5dd2c07b34.gif) 这样一个文档就生成好了。但是感觉有点不好看啊,没关系可以改一改参数, ![勾选JAVADOC_AUTOBRIEF](https://img-blog.csdnimg.cn/6bb6f582a91b42578427e9d653252162.png) ![勾选EXTRACT_ALL](https://img-blog.csdnimg.cn/7d61efde632e40d984bcc0161264e756.png) ![取消SHOW_USED_FILES](https://img-blog.csdnimg.cn/cb8424adfe304fb79610da90b5a37b16.png) ![](https://img-blog.csdnimg.cn/22e96bcb9eda40ffafae049c517a6318.png) 按照上面四张图的**配置勾选**,在**再生**成一次就可以了,现在可以看到树图就显示在最左边了,符合我们的观看形式。 ![](https://img-blog.csdnimg.cn/c72643dcda114373b6592fd123f47ff9.png) 还可以把**英文**变成**中文**。 ![选择chinese](https://img-blog.csdnimg.cn/6fdd3ef0d80442518df1a997a912249f.png) 再次生成就变成中文的了。 ![静态图](https://img-blog.csdnimg.cn/bd5fd99c8019483b9e5cce78554a73fa.png) ![动态演示效果](https://img-blog.csdnimg.cn/521e6295456740f097cb8a6f5cb155a5.gif) 这样一个文档说明就做好了。这时你只能在你的电脑上面找到`index.html`文件才能查看,如果想实时随时随地的查看就需要把他放到你的服务器上面了,可以通过网络访问。 # 6、Nginx本地访问 Nginx是一款是由俄罗斯的程序设计师Igor Sysoev所开发高性能的Web和反向代理服务器。首先下载Nginx。网址:http://nginx.org/en/download.html。 ![](https://img-blog.csdnimg.cn/f9677dd0356949209b435eddf0a6ab6c.png) 如果打开`Nginx.exe`出现闪退。解决办法:`nginx`路径不许是英文的,不可以有中文路径。更改完后重新启动`nginx.exe`查看进程中是否有`nginx`。再在浏览器中输入地址`localhost`,正常打开即可。 ![](https://img-blog.csdnimg.cn/78662a1bca5148ddba654fb71a9956a6.png) 然后我们通过`doxygen`生成的文件放入`nginx`的`html文`件夹中。 ![](https://img-blog.csdnimg.cn/5bb613f773834ef9b4dc08b0cf0b44e1.png) 然后在浏览器输入:`http://localhost/doxygen/index.html`,就可以正常访问了。 ![](https://img-blog.csdnimg.cn/1c04855e46eb438baf334c4b4d115b05.png) 然后你可以把这个网页收藏起来,就再也不用每次去文件夹找index.html文件访问文档了,这样就非常的方便。当然你也可以把这个文件**托管到gitee或者github**上面就更加方便了。 >1.Doxygen并不处理所有的注释,doxygen重点关注与程序结构有关的注释,比如:文件、类、结构、函数、全局变量、宏等注释,而忽略函数内局部变量、代码等的注释。 2.注释应写在对应的函数或变量前面。 3.先从文件开始注释,然后是所在文件的全局函数、结构体、枚举变量、命名空间→命名空间中的类→成员函数和成员变量。 4.Doxygen无法为DLL中定义的类导出文档。 ![](https://cf01.ickimg.com/bbsimages/202108/972395e2b0fae5988112a22d7a939d42.png)
原创作品,未经权利人授权禁止转载。详情见
转载须知
。
举报文章
点赞
(
0
)
果果小师弟
关注
评论
(0)
登录后可评论,请
登录
或
注册
相关文章推荐
MK-米客方德推出工业级存储卡
Beetle ESP32 C3 蓝牙数据收发
Beetle ESP32 C3 wifi联网获取实时天气信息
开箱测评Beetle ESP32-C3 (RISC-V芯片)模块
正点原子数控电源DP100测评
DP100试用评测-----开箱+初体验
Beetle ESP32 C3环境搭建
【花雕体验】16 使用Beetle ESP32 C3控制8X32位WS2812硬屏之二
X
你的打赏是对原创作者最大的认可
请选择打赏IC币的数量,一经提交无法退回 !
100IC币
500IC币
1000IC币
自定义
IC币
确定
X
提交成功 ! 谢谢您的支持
返回
我要举报该内容理由
×
广告及垃圾信息
抄袭或未经授权
其它举报理由
请输入您举报的理由(50字以内)
取消
提交