doxygen介绍

相信学习嵌入式开发的人都知道,在官方头文件中总是有很多酷炫的注释。 我一直很疑惑,这些注释到底有什么用,直到我看到了doxygen才明白。

使用目的

doxygen会根据你代码中的注释,自动生成文档,可以是html,也可以是pdf。 这些文档可以让别人快速了解你的API,并使用它。

安装与使用

  • 下载安装doxygen
  • 使用方法
    • windows下使用
      • 你需要稍微了解一下windows命令行常用命令
      • 可以选择使用powershell
      • 打开命令行,cd到你要生成文档的源文件的位置,在命令行输入

        1
        doxygen -g

      • 成功后,当前目录生成一个Doxyfile的配置文件,并显示以下信息

        1
        2
        3
        4
        Configuration file `Doxyfile' created.
        Now edit the configuration file and enter
        doxygen Doxyfile
        to generate the documentation for your project

      • 接下来就可以对Doxyfile进行修改
        • 如果不需要PDF输出就把
          1
          GENERATE_LATEX         = YES

        修改为

        1
        GENERATE_LATEX         = NO

        • 配置文件里有相关配置的描述,可以参考下
      • 修改配置文件结束后,就可以进行文档的输出了,在命令行输入以下命令

        1
        doxygen .\Doxyfile

使用方法参考Doxygen 10 分钟入门教程

doxygen注释风格

命令          说明
@file 档案的批注说明
@author   作者信息
@brief     简要说明
@param     参数说明
eg:参数a + ' ' + 作用
@return 描述该函数的返回值情况
@retval 描述返回值类型
@note 注解
@attention   注意
@warning 警告信息
@enum 引用了某个枚举,Doxygen会在该枚举处产生一个链接
@var 引用了某个变量,Doxygen会在该枚举处产生一个链接
@class 引用某个类
@exception   可能产生的异常描述                                

参考来源Doxygen注释风格 ## 可能出现的问题 1. 中文输出乱码

![](/img/doxygen/garbled1.png)
  • 解决方法
    • 修改Doxyfile
      1
      INPUT_ENCODING = GB2312

  - 修改后效果图