doxygen介绍

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

使用目的

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

安装与使用

  • 使用方法

    • 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. 中文输出乱码

    • 解决方法

      • 修改Doxyfile
        1
        INPUT_ENCODING = GB2312
    • 修改后效果图