doxygen文件配置

主要配置修改

整个程序配置分几个部分

1. Project related configuration options
   
   项目相关，包括：
   • 项目名
   • 输出目录
   • 输出语言
   • 是否显示继承属性
   • 是否对C、Java、Fortran等优化
2. Build related configuration options
   • 是否显示私有、静态变量
   • 是否显示 include 文件
   • 是否将文件中brief descriptions重新排序
   • 显示文件
   • 显示作用域
3. Configuration options related to warning and progress messages
4. Configuration options related to the input files
   • 源文件位置
   • 字符编码
   • 图片位置
5. Configuration options related to source browsing
   • 是否显示源程序
   • 忽略程序注释
   • 是否显示调用、被调用相关函数
6. Configuration options related to the alphabetical class index
7. Configuration options related to the HTML output
8. Configuration options related to the LaTeX output
9. Configuration options related to the RTF output
10. Configuration options related to the man page output
11. Configuration options related to the XML output
12. Configuration options related to the DOCBOOK output
13. Configuration options for the AutoGen Definitions output
14. Configuration options related to the Perl module output
15. Configuration options related to the preprocessor
16. Configuration options related to external references
17. Configuration options related to the dot tool

运行使用

doxygen [Doxygen file]

注释

参考自Doxygen注释风格。

要点

若想要通过Doxygen生成漂亮的文档，有几个地方需要使用Doxygen支持的风格进行注释：

1. 头文件
   
   声明版权，描述文件实现功能，及文件版本信息；
2. 类、结构体定义
   
   描述类或结构体实现的功能，同时也可以包含使用方法或注意事项的简要描述；
3. 类、结构体成员定义
   
   在成员变量的上方进行简要描述；
4. 类成员函数、子例程函数定义
   
   函数功能简要描述；
5. 函数的详细定义
   
   函数实现位置处对函数的功能、参数的含义、返回值的含义、使用本函数需要注意的问题、本函数使用其他类或函数的说明等进行详细描述。

注释指令

常用doxygen变量

变量名	说明
@file	文件的批注说明
@author	作者的信息
@brief	用于class 或function的简易说明
@param	函数中参数的说明
@return	函数的返回情况
@retval	描述返回值类型
@note	注解
@attention	注意说明
@warning	警告

JavaDoc注释风格

在C风格注释块开始使用两个星号 *

/**
 * ... 描述 ...
 */

简要描述

/**   Brief description
 *    description continued
 *
 *    Detailed description starts here.
 */

变量描述

/** Detailed description before the variable */

int m_Var;

使用CMake配置doxygen输出文件

在doc文件夹内添加doxygen配置文件Doxyfile.in，对应的CMakeLists.txt文件写为

find_package(Doxygen)
option(BUILD_DOCUMENTATION "Create and install the HTML based API documentation (requires Doxygen)" ${DOXYGEN_FOUND})

if(BUILD_DOCUMENTATION)
    if(NOT DOXYGEN_FOUND)
        message(FATAL_ERROR "Doxygen is needed to build the documentation.")
    endif()

    set(doxyfile_in ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
    set(doxyfile ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)

    # copy the content from `Doxyfile.in` to `Doxyfile`, replace the @VAR@ variables
    configure_file(${doxyfile_in} ${doxyfile} @ONLY)

    add_custom_target(doc
        COMMAND ${DOXYGEN_EXECUTABLE} ${doxyfile}
        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
        COMMENT "Generating API documentation with Doxygen"
        VERBATIM)

    install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html DESTINATION share)
endif()

其中configure_file命令会按照Doxyfile.in文件内容新生成一个新的文件，参数@ONLY指定文件Doxyfile.in内@VAR@形式的参数会使用CMake变量进行替换。

以上文件全部配置完成后，使用命令make doc即可生成doxygen说明文档。