【转】Doxygen制作软件说明文档

https://mp.weixin.qq.com/s/FDN5kED12k8-PMEqMvU3hw

摘要：写代码容易、维护难，主要体现在代码说明文档难写或者直接不写，Source Insight+Doxygen组合，自动补齐注释，并生成标准接口文档。

1、需求

如下图函数注释：

或者结构体、枚举注释：

或者一些开源代码、芯片原厂SDK文档，如下图：

如何将自己的代码也打包成这样的说明文档呢？

2、Source Insight注释模板

阅读本文前先熟悉Source Insight的操作，如何定义注释模板，可以参考代码的保养。

3、Doxygen注释转换

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了。

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 }
@remarks备注remarks { description }以上写注释时必须使用的关键字，但是实际操作中并不需要全部，按需使用部分即可。

2.文件注释

一般放在文件开头

复制

/**

 * [url=home.php?mod=space&uid=288409]@file[/url] 文件名

 * [url=home.php?mod=space&uid=247401]@brief[/url] 简介

 * [url=home.php?mod=space&uid=1543424]@Details[/url] 细节

 * [url=home.php?mod=space&uid=187600]@author[/url] 作者

 * [url=home.php?mod=space&uid=895143]@version[/url] 版本号

 * [url=home.php?mod=space&uid=212281]@date[/url] 年-月-日

 * [url=home.php?mod=space&uid=17282]@CopyRight[/url] 版权

 */

示例

3.结构体注释

复制

 /**

 * @brief 类的详细描述

 */

示例

4.函数注释

复制

 /**

  * @brief 函数描述

  * @param 参数描述

  * [url=home.php?mod=space&uid=266161]@return[/url] 返回描述

  * @retval 返回值描述

  */

实例

5.常量/变量注释

一般常量/变量可以有两种形式：

• 常量/变量上一行注释
• 常量/变量后注释
  复制

  //定义一个整型变量a
  
  int a;
  
  
  
  /**
  
   * @brief 定义一个整型变量a
  
  */
  
  int a;

  复制

  int a; /*!< 定义一个整型变量a */
  
  int a; /**< 定义一个整型变量a */
  
  int a; //!< 定义一个整型变量a
  
  int a; ///< 定义一个整型变量a

  
  

5、使用Doxygen软件

上面是常规注释格式，然后使用Doxygen软件生成文档。使用Doxygen软件把SDK软件包代码生成一份文档，文档包含了所有的函数与结构体，这样别人在阅读或使用代码时就直观便捷许多。

1、打开Doxygen软件。

2、选择运行doxygen的工作目录，就是SDK软件包在哪个文件夹。

doxygen 的工作目录

3、接着填写一些生成文档的一些信息，包括文档名称、简介、版本、源码文件路径、生成的文档路径。

4、选择生成文档的格式，默认可以生成html和tatex格式的。

5、最后再run选项卡中点击Run doxygen就可以生成了。

6、在生成的目录中找到index.html文件打开即可。

浏览器打开

这样一个文档就生成好了。但是感觉有点不好看啊，没关系可以改一改参数，

勾选JAVADOC_AUTOBRIEF

勾选EXTRACT_ALL

取消SHOW_USED_FILES

按照上面四张图的配置勾选，重新生成一次就可以了，现在可以看到树图显示在最左边了，符合我们的观看形式。

还可以把英文变成中文。

选择chinese

再次生成就变成中文的了。

静态图

动态演示效果

这样一个文档说明就做好了。这时你只能在你的电脑上面找到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。

• Doxygen并不处理所有的注释，doxygen重点关注与程序结构有关的注释，比如：文件、类、结构、函数、全局变量、宏等注释，而忽略函数内局部变量、代码等的注释。

• .注释应写在对应的函数或变量前面。

• .先从文件开始注释，然后是所在文件的全局函数、结构体、枚举变量、命名空间→命名空间中的类→成员函数和成员变量。

• .Doxygen无法为DLL中定义的类导出文档。

  
  

[size=1.2em]补充：CHM文档

HTML格式文件零散，拷贝起来特别不方便，可以转成chm格式而方便转发分享。

配置Source Insight，按照Doxygen关键字的格式要求，定义注释模板，最后将生成的html说明文档转成chm单文件，软件的长期维护才能更加轻松。

我用doxygen生成文档的时候，函数中间的注释有时候也会被提取到文档中去？楼主知道再哪里设置取消这个吗？