干货|教你使用Doxygen制作漂亮的程序文档
击上方“果果小师弟”，选择“置顶/星标公众号”
干货福利，第一时间送达！
摘要：不知道大家有没有把自己的代码整理成文档的习惯，有没有给自己的代码一个非常漂亮的注释，就像下图这样。
如果你写了一个结构体或者枚举是否也是这样注释的？
如果每个人的注释都是这样写的话，被人怎么可能看不懂你的代码？如果你不是这样的话，你就必须要看这篇文章了。
等等，别走！还有~
你是不是也看过很多说明文档，比如下面这样的关于STM32标准外设驱动文档。你有没有想象过自己的代码也是可以这样打包成这样一个非常漂亮的文档的？
今天就教大家如何给写注释，如何写出漂亮规范的注释，让人看着心旷神怡，透人心脾。如何写出规范的说明文档，让人看了直呼内行，给你点赞！
Doxygen能将程序中的特定批注转换成为说明文件。它可以依据程序本身的结构，将程序中按规范注释的批注经过处理生成一个纯粹的参考手册，通过提取代码结构或借助自动生成的包含依赖图、继承图）以及协作图来可视化文档之间的关系，Doxygen生成的帮助文档的格式可以是CHM、RTF、PostScript、PDF、HTML等。
微软出品的HTML Help WorkShop是制作CHM文件的最佳工具，它能将HTML文件编译生成CHM文档。Doxygen软件默认生成HTML文件或Latex文件，我们要通过HTML生成CHM文档，需要先安装HTML Help WorkShop软件，并在Doxygen中进行关联即可。
下面将按照这张思维导图来讲述如何安装软件，以及如何写单片机注释和最终如何导出文档。
1、windows安装doxygen
首先在官网下载doxygen，网址：https://www.doxygen.nl/download.html
下载完成后傻瓜式一步一步安装就可以了。安装完成后在开始栏点击Doxywizard就可以打开软件了。
2、Linux安装doxygen
这里我是使用的是ubuntu虚拟机，使用sudo apt-get install doxygen就可以安装了。
安装完成后在命令行输入doxygen,如果出现帮助信息，说明安装成功，如果出现command not font则表明安装失败。之后使用sudo apt-get install doxygen-gui安装gui，就可以像windows那样使用图形化操作了。安装完成后使用doxygenwizard命令就可以打开doxygen了。
sudo apt-get install doxygen
sudo apt-get install doxygen-gui
如何在ubuntu上创建快捷方式，自行百度。
3、MacOS安装doxygen
首先在官网下载MacOS版本的安装包。下载完成后，直接把他拖到application上面就可以了。
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.文件注释
一般放在文件开头
/**
* @file 文件名
* @brief 简介
* @details 细节
* @author 作者
* @version 版本号
* @date 年-月-日
* @copyright 版权
*/
示例
3.结构体注释
/**
* @brief 类的详细描述
*/
示例
4.函数注释
/**
* @brief 函数描述
* @param 参数描述
* @return 返回描述
* @retval 返回值描述
*/
实例
5.常量/变量注释
一般常量/变量可以有两种形式：
常量/变量上一行注释 常量/变量后注释
//定义一个整型变量a
int a;
/**
* @brief 定义一个整型变量a
*/
int a;
int a; /*!< 定义一个整型变量a */
int a; /**< 定义一个整型变量a */
int a; //!< 定义一个整型变量a
int a; ///< 定义一个整型变量a
5、使用Doxygen软件
上面说了半天就是想主要是让大家规范注释，然后使用Doxygen软件生成文档后会规范一些。我们以keil软件为例，使用Doxygen软件把我们的keil工程代码生成一份文档，这个文档包含了所有的函数与结构体，以及我们定义的所有函数，这样别人在看你的代码时就方便多了。
1、打开Doxygen软件。
2、选择运行doxygen的工作目录，就是你的keil工程在哪一个文件夹，这里就定位到那个文件夹。
3、接着填写一些生成文档的一些信息，包括文档名称、简介、版本、源码文件路径、生成的文档路径。
4、选择生成文档的格式，默认可以生成html和tatex格式的。
5、最后再run选项卡中点击Run doxygen就可以生成了。
6、在生成的目录中找到index.html文件打开即可。
这样一个文档就生成好了。但是感觉有点不好看啊，没关系可以改一改参数，
按照上面四张图的配置勾选，在再生成一次就可以了，现在可以看到树图就显示在最左边了，符合我们的观看形式。
还可以把英文变成中文。
再次生成就变成中文的了。
这样一个文档说明就做好了。这时你只能在你的电脑上面找到index.html文件才能查看，如果想实时随时随地的查看就需要把他放到你的服务器上面了，可以通过网络访问。
6、Nginx本地访问
Nginx是一款是由俄罗斯的程序设计师Igor Sysoev所开发高性能的Web和反向代理服务器。首先下载Nginx。网址：http://nginx.org/en/download.html。
如果打开Nginx.exe出现闪退。解决办法：nginx路径不许是英文的，不可以有中文路径。更改完后重新启动nginx.exe查看进程中是否有nginx。再在浏览器中输入地址localhost，正常打开即可。
然后我们通过doxygen生成的文件放入nginx的html文件夹中。
然后在浏览器输入：http://localhost/doxygen/index.html，就可以正常访问了。
然后你可以把这个网页收藏起来，就再也不用每次去文件夹找index.html文件访问文档了，这样就非常的方便。当然你也可以把这个文件托管到gitee或者github上面就更加方便了。
“1.Doxygen并不处理所有的注释，doxygen重点关注与程序结构有关的注释，比如：文件、类、结构、函数、全局变量、宏等注释，而忽略函数内局部变量、代码等的注释。2.注释应写在对应的函数或变量前面。3.先从文件开始注释，然后是所在文件的全局函数、结构体、枚举变量、命名空间→命名空间中的类→成员函数和成员变量。4.Doxygen无法为DLL中定义的类导出文档。
”
End
推荐好文 点击蓝色字体即可跳转
欢迎转发、留言、点赞、分享，感谢您的支持!
分享 💬 点赞 👍 在看 ❤️
以“三连”行动支持优质内容!