what

doxygen是一个自动根据注释生成文档的工具。支持html、chm、pdf等格式。

安装

源码
github
编译安装
工程使用cmake组织。会缺少一些依赖，缺啥补啥就行。

生成文档的步骤

按照doxygen的规范进行代码注释
生成一个配置文件，根据自己的需要修改参数
调用doxygen生成文档

实验1：生成doxygen的文档。

准备源码
doxygen的代码本身就是按照自己的格式注释的，这里不需要操作。
生成配置文件
-doxygen –g
生成不带注释的：doxygen -s –g
配置文件的修改参数
参数都有注释，可以简单修改一下类似工程名、语言这些基本配置，也可以不改。
进入源码目录，执行doxygen your-cfg-filename
这就会生成一个html的文档。
image.png

这样就会生成一份doxygen自己的文档。

doxygen配置主要参数：

PROJECT_NAME = “Test”
PROJECT_NUMBER = 1.0.0
OUTPUT_DIRECTORY = doc/
OPTIMIZE_OUTPUT_FOR_C = NO
c++这里就用NO
TYPEDEF_HIDES_STRUCT = YES
定义的结构体、枚举、联合等数据类型，只按照 typedef定义的类型名进行文档化
GENERATE_LATEX = NO
默认会生成一个html和latex的文档，有html就够了。
RECURSIVE = YES
是否递归调用
GENERATE TREEVIEW ＝ ALL
这会在HTML文档中，添加一个侧边栏，并以树状结构显示包、类、接口等的关系

注释规范

单行注释
用“//!”来表示，例如：//!概要
多行注释

/*!
xx@#$%~
xx^&*(
*/

各种标记
一些类似param、return这些标记，doxygen会解释这些标记。可以用@链接这些标记，也可以用\
b 加粗
param 参数
tparam 模板参数
code和encode用于表示一个代码块

  SomeClass sc("hello");
  string result;
  int ret = sc.Func("world",3,result);
  \endcode

note 说明注释
return 返回值
todo 待做的
deprecated 启用的
使用@分组

//! @name operator
    //@{
        bool operator==(const SomeClass& other) const { return true;} 
        bool operator!=(const SomeClass& other) const { return true;} 
        bool operator<(const SomeClass& other) const { return true;} 
        bool operator>(const SomeClass& other) const { return true;} 
    //@}

完整的示例：

代码：

#pragma once

/*! \file document.h */

#include <string>
#include <vector>

using namespace std;

//!概要
/*!
    具体注释：

    \tparam 模板参数的注释
    \see SomeClass::SomeClass

    这就是一个测试类。

    \b "\b"表示加粗
    \code 
    SomeClass sc("hello");
    string result;
    int ret = sc.Func("world",3,result);
    \endcode
*/
template<typename Type>
class SomeClass
{
public:
    /*!
        构造函数

        \param str 输入字符串

        \note 说明
    */
    SomeClass(string const& str){}

    //! 函数注释概要
    /*!
        具体解释
        \li 解释1
        \li 解释2
        \li 解释3

        \param outStr 输出字符串

        \return int 错误码,0表示成功

        \todo 对各种错误进行整理
    */
    int Func(string const& str,int len, string& outStr)
    {
        return 0;
    }

    //! \deprecated
    int Func()
    {
        return 0;
    }

    //! @name operator
    //@{
        bool operator==(const SomeClass& other) const { return true;} 
        bool operator!=(const SomeClass& other) const { return true;} 
        bool operator<(const SomeClass& other) const { return true;} 
        bool operator>(const SomeClass& other) const { return true;} 
    //@}
public:
    string value_;

private:
    int len_;
    Type type_;
}