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

目前Doxygen可处理的程序语言包含C/C++JavaObjective-CIDL等,可产生出来的文档格式有HTMLXMLLaTeXRTF等,此外还可衍生出不少其它格式,如HTML可以打包成CHM格式,而LaTeX可以通过一些工具产生出PS或是PDF文档等。

即: 通过代码里面的注释,生成htmlchm这一类的手册说明,极其类似于qt帮助文档

[TOC]


本文初发于 “偕臧的小站“,同步转载于此。


同步博文:


下载doxygen:

官网: http://www.doxygen.nl/download.html

支持Windows/macOS/Linux平台(简直就是好人)


Linux下使用dexygen生成文档:

这里在deepin v20( Linux) 演示:

  • 安装命令
    sudo apt install doxygen
    截止到我安装的时候, 最新的版本是1.8.13 (2019-10-29官网Linux版下载)
  • 进入到工程项目文件夹下~/projects/dtkwidget, 使用如下命令生成Doxyfile文件(这是一个配置文件)
    doxygen -g      //生成带详细注释的Doxyfile文件 约2120行
    //或
    doxygen -s -g   //生成不带详细注释的Doxyfile文件  约374行
  • 编辑使用vim编辑如下的Doxyfile文件; 其中这几点必须修改, 不然可能和预期的效果不一样

    //必须要填写:
    OUTPUT_DIRECTORY       =/home/yuanyi/projects/out //输出存放文档的路径
    RECURSIVE              = YES //文件递归,包括子文件也要输出为文档
    IMAGE_PATH              = ./doc/images //若是想要文档里面插入图片,需要存放图片路径

    //推荐修改
    PROJECT_NAME            = “My Project” //生成文档的名称
    OUTPUT_LANGUAGE        = Chinese //生成文档为中/英文 English
    PROJECT_NUMBER =1.0.0 //项目文档的版本号码

  • 生成的Doxyfile文件是必须放在工程项目的根目录下~/[projects/dtkwidget](file:///home/yuanyi/projects/dtkwidget),默认也是生成在这里的
    ├── dtkwidget
        ├── ...很多文件及文件夹
        ├── doc
        ├── Doxyfile
        ├── LICENSE
        └── README.md
  • 在项目里面, 添加符合doxygen规则的代码注释, 便于生成文档
  • 运行命令生成文档的
    doxygen     //默认是等价于下面的doxygen Doxyfile,也可执行自定义Doxyfile文件
    //或
    doxygen Doxyfile
  • 到输出目录查看生成的html文件夹,使用浏览器打开index.html文件, 其像动态网站一样, 帮助你早日熟悉项目工程的结构

生成其他格式如chm和注意:

这里是可以很多其他格式的, 一些常用的设置, 参考下图:

# 如果是制作 C 程序文档,该选项必须设为 YES,否则默认生成 C++ 文档格式
OPTIMIZE_OUTPUT_FOR_C  = YES