Doxygen生成帮助文档

介绍

• Doxygen是一个通过注释生成帮助文档的工具，可以编写doxygen风格的注释，生成HTML文档，vtk就使用该技术生成帮助文档
• Graphviz是一个可视化工具，可以给帮助文档生成类关系图

前提

1. 下载doxygen
2. 下载graphviz
3. 下载cmake
   上述都需要添加到系统环境变量

编写doxygen风格注释

• 项目目录

  doxygen_example
  ├── CmakeLists.txt
  ├── Doxyfile.doxygen
  ├── mainpage.md
  ├── QTstyle_Test.h
  └── QTstyle_Test1.h
  

  • QTstyle_Test.h

//!  A test class. 
/*!
  A more elaborate class description.
*/
class QTstyle_Test
{
     
  public:
    //! An enum.
    /*! More detailed enum description. */
    enum TEnum {
      
                 TVal1, /*!< Enum value TVal1. */  
                 TVal2, /*!< Enum value TVal2. */  
                 TVal3  /*!< Enum value TVal3. */  
               } 
         //! Enum pointer.
         /*! Details. */
         *enumPtr, 
         //! Enum variable.
         /*! Details. */
         enumVar;  
    
    //! A constructor.
    /*!
      A more elaborate description of the constructor.
    */
    QTstyle_Test();
    //! A destructor.
    /*!
      A more elaborate description of the destructor.
    */
   ~QTstyle_Test();
    
    //! A normal member taking two arguments and returning an integer value.
    /*!
      \param a an integer argument.
      \param s a constant character pointer.
      \return The test results
      \sa QTstyle_Test(), ~QTstyle_Test(), testMeToo() and publicVar()
    */
    int testMe(int a,const char *s);
       
    //! A pure virtual member.
    /*!
      \sa testMe()
      \param c1 the first argument.
      \param c2 the second argument.
    */
    virtual void testMeToo(char c1,char c2) = 0;
   
    //! A public variable.
    /*!
      Details.
    */
    int publicVar;
       
    //! A function variable.
    /*!
      Details.
    */
    int (*handler)(int a,int b);
};

• QTstyle_Test1.h

//!  A test class. 
/*!
  A more elaborate class description.
*/
class QTstyle_Test1
    :public QTstyle_Test
{
     
  public:
    QTstyle_Test1();
    ~QTstyle_Test1();
};

• mainpage.md

# Introduction
this is an example of doxygen documentation.
# Class
* QTstyle_Test
* QTstyle_Test1

• 更多例子请访问doxygen官网

doxygen设置

• 工作目录：整个代码的目录
• 基本设置：可以设置项目名、简要描述、版本号、项目LOGO
• 源代码目录：源码所在目录，如果选择了递归搜索，那么doxygen将会递归遍历整个代码目录
• 目标目录：帮助文档生成的目录
  注意：源码目录和目标目录可以是基于工作目录的相对路径
• 选择c++文档生成选项
  
• 选择生成的文档为HTML格式文档
  
• 选择dot，则会生成类之间的关系图
  
• 默认编码为UTF-8，语言为英语；如果要设置其他的语种，则需要改变默认编码和语言
  
• FILE-PATTERNS: 指定需要生成文档的文档后缀名
  
• EXCLUDE-PATTERNS:指定源码目录中不用于生成的文件夹或文件，如果是文件夹，格式是*/foldername/*，如果是文件，直接写文件名
  
• USE-MDFILES-AS-MAINPAGE:指定主页是否要使用md文件作为主页
  
• 点击run生成帮助文档，还可以点击show configuration和save log查看或保存当前配置
  
• 帮助文档大概样子
  
  

使用CMake生成帮助文档

• 源码目录下创建一个CMakeLists.txt文件，添加以下代码：

CMAKE_MINIMUM_REQUIRED(VERSION 3.10)
project(Andyfan)
option(BUILD_DOXY_DOC "build doxygen documentation" ON)
if(BUILD_DOXY_DOC)
	find_package(Doxygen)
	if(NOT DOXYGEN_FOUND)
		message(WARNING "Doxygen not found, unable to generate documentation")
	else()
		set(DOXYGEN_PROJECT_NAME "ANDYFAN")
		set(DOXYGEN_REPEAT_BRIEF YES)
        set(DOXYGEN_USE_MDFILE_AS_MAINPAGE "{CMAKE_CURRENT_SOURCE_DIR}/mainpage.md")
        set(DOXYGEN_EXCLUDGE_PATTERNS "*/folder/*" "filename.h")
		doxygen_add_docs(
		doxygen
		WORKING_DIRECTORY  ${PROJECT_SOURCE_DIR}
		COMMENT "this is my cmake help doc testing"
		)
	endif()
endif()

• 使用CMake构建VS项目，编译就可以在vs下生成帮助文档
  
  
• 一些需要注意的地方

1. doxygen和graphviz都要添加到环境变量中
2. 通过CMake的set命令设置doxygen的变量，例如，如果你要在doxygen配置文件中设置XXX变量，那么使用命令set(DOXYGEN_XX value),每个设置都要加上DOXYGEN_前缀，下表格中有一些设置相关例子

   Doxygen	CMake
   PROJECT_NAME(string)	set(DOXYGEN_PROJECT_NAME “name”)
   REPEAT_BRIEF(bool)	set(DOXYGEN_REPEAT_BRIEF YES)
   EXCLUDE_PATTERNS(array)	set(DOXYGEN_EXCLUDE_PATTERNS “* /folder/ *” “filename.cpp”)
   PROJECT_LOGO	set(DOXYGEN_PROJECT_LOGO “full logo file path”)
   USE_MDFILE_AS_MAINPAGE	set(DOXYGEN_MDFILE_AS_MAINPAGE “full md file path”)