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_;
}

• 生成的文档如下：

  
  image.png
  image.png
  image.png