代码说明书生成神器—Doxygen

Posted 2022-03-21 嵌入式基地

Doxygen是一个程序的文档产生工具，可以将程序中的注释转换成说明文档或者说是API参考手册，从而减少程序员整理文档的时间。当然这里程序中的注释需要遵循一定的规则书写，才能让Doxygen识别和转化。

目前Doxygen可处理的程序语言包含C/C++、Java、Objective-C、IDL等，可产生出来的文档格式有html、XML、LaTeX、RTF等，此外还可衍生出不少其它格式:

• HTML可以打包成CHM格式，而LaTeX可以通过一些工具产生出PS或是PDF文档等。
• 可以利用Doxygen给C，C++程序生成注释文档

本文会以STM32F1系列单片机的标准库（Standard Peripheral Library）为例来讲解Doxygen的使用，该驱动库文件的注释书写十分标准，很适合进行学习模仿。

软件下载

官网下载

Doxygen

• 下载地址：https://sourceforge.net/projects/doxygen/ 或 http://www.doxygen.nl/download.html

HTML Help：微软官方用于生成HTML格式的help文件。

• 下载地址：https://docs.microsoft.com/zh-cn/previous-versions/windows/desktop/htmlhelp/microsoft-html-help-downloads?redirectedfrom=MSDN

Graphviz：一种dot工具可以用来渲染出效果更好的图表。

• 下载地址：https://graphviz.org/download/

百度网盘下载

在本公众号后台回复：Doxygen 获取下载链接

使用教程

1.设置doxygen工程工作目录

2.设置编程语言

• 选择编程语言对应的最优化结果，按照编程语言选择。
  

3.设置文档输出格式

• 选择输出格式，选HTML下的（.chm）项，为最后生成chm做准备。
  

4.设置生成的关系表

• 选择dot tool项，通过GraphViz来作图。
  

5.设置输出的语言，编码

• 选择输出目录
• 选着输出语言，如果代码中采用了中文注释，此处选择为中文
• JAVADOC_AUTOBRIEF和QT_AUTOBRIEF两个框，如果勾选了，在这两种风格下默认第一行为简单说明，以第一个句号为分隔；如果不选，则需要按照Doxygen的指令@brief来进行标准注释。
  

6.设置一些构建的选择项

• 需要勾选EXTRACT_ALL和LOCAL_METHODS才能生成所有的变量和函数
  

7.设置输入文件的编码

8.设置是否在.chm中生成源码以供预览

9.设置HTML选项

• 勾选生成HTMLHELP项
• 输入生成CHM名称
• 在HHC_LOCATION中填入HTMLHELP WORKSHOP安装目录中hhc.exe的路径
  

10.设置Dot选项

• 在Dot_PATH中填写GraphViz的安装路径。
  
  

11.生成说明文档

• 点击Run doxygen
  

生成文档预览

html格式文档预览

• 双击打开index.html文件即可
  

chm格式文档预览

• 双击打开stm32f10x_fwlib.chm文件即可
  
  关注v-x-公-众-号：【嵌入式基地】
  后-台-回-复：【电赛】 即可获资料
  回复【编程】即可获取
  包括有：C、C++、C#、JAVA、Python、javascript、php、数据库、微信小程序、人工智能、嵌入式、Linux、Unix、QT、物联网、算法导论、大数据等资料