doxygen生成html文档

一、注释语法

1. 简单注释

   单行注释：    ///
   多行注释：    /**
   

2. 文件注释

   /**
    *  @file test.h
    *  @brief 测试doxygen
    *  @details 详细描述
    *  详细描述2
    *  @author ...
    *  @email 油箱
    *  @version v1.1.1
    *  @date 2020-01-10
    *  @license 版权
    */ 
   

3. 命名空间注释

4. 类定义注释

   /**
    *  @brief 测试命名空间
    */ 
   

5. 变量/宏定义注释

   int id_;            ///< 用户ID
   std::string name_;  ///< 用户名
   /// 用户薪水
   double salary_;
   

6. 函数注释

   /**
    * @brief 测试函数
    *
    * @param[in] in_argv 第一个参数
    * @return 成功与否
    *  @retval 1 成功
    *  @retval 0 失败
    * @attention 注意释放内存
    * @warning 测试警告
    * @execption 异常
    */
   int func_test(const std::string& in_argv){
    return 0;
   }
   

7. 其他

   命令	说明
   @see	参考
   @class	引用类
   @var	引用变量
   @enum	引用枚举
   @code	代码块开始
   @endcode	代码块结束
   @bug	缺陷
   @todo	TODO
   @example	使用例子说明
   @remarks	备注说明
   @pre	函数前置条件
   @deprecated	函数过失说明

8. 完整示例

/**
*  @file test.h
*  @brief 测试doxygen
*  @details 详细描述
*  详细描述2
*  @author ...
*  @email 油箱
*  @version v1.1.1
*  @date 2020-01-10
*  @license 版权
*/
#pragma once
#include 
/**
*  @brief 测试命名空间
*/ 
namespace CppNamespace
{
/// 宏定义
#define BUFSIZE 1000

/// 测试枚举
enum CppEnum {
  SALARY_Millions,            ///< 枚举1
  SALARY_Million_OF_Million   ///< 枚举2
};

/**
*  @brief 测试结构体声明
*/
struct CppStruct{
  int id_;            ///< 用户ID
  std::string name_;  ///< 用户名
  /// 用户薪水
  double salary_;
}


/**
*  @brief 测试类
*  主要用来演示doxygen类的注释方式
*/
class CppClass
{
public:
  CppClass() {}
  ~CppClass() {}

public:
  /**
   * @brief 测试函数
   *
   * @param[in] in_argv 第一个参数
   * @return 成功与否
   *  @retval 1 成功
   *  @retval 0 失败
   * @attention 注意释放内存
   * @warning 测试警告
   * @execption 异常
   */
  int func_test(const std::string& in_argv){
      return 0;
  }
private:

};
};

二、生成html文档

1. 安装doxygen

   // ubuntu
   sudo apt install doxygen
   sudo apt install doxygen-gui
   sudo apt install graphviz-doc
   

2. 使用doxywizard工具生成Doxyfile

   // 运行doxywizard
   doxywizard
   

   2.1 填写基本信息

   working directory:              工作目录
   project name:                   工程名称
   source code:                    源码路径，勾选递归遍历
   destination directory:    html  存储路径
   

   填写信息

   2.2 选择Run 标签，执行Run doxygen

   Run doxygen

   2.3 保存Doxyfile

    菜单->File->Save
   

3. 生成结果目录

   ├── html
   │   ├── html
   │   └── latex
   ├── inc
   │   └── test.h
   ├── readme.md
   ├── src
   │   └── test.cpp
   

4. 查看文档

![查看文档](https://upload-images.jianshu.io/upload_images/17115723-12c9090b4e3d8890.png?imageMogr2/auto-orient/strip%7CimageView2/2/w/1240)

5. 也可以使用docker部署nginx，查看文档

   5.1. 下载镜像

   docker pull nginx
   

   5.2. 创建nginx容器

   // 映射本地html的路径到容器中/var/html路径
   docker run --name nginx -d -p 80:80 -v /data:/var/html/ nginx
   // 或者不映射，使用docker cp 复制到容器中也可以
   

   5.3. 修改nginx配置文件

   docker exec -it nginx
   apt update
   apt install vim
   vim /etc/nginx/conf.d/default.conf
   // 修改如下内容
   location / {
      root    /var/html;
      index   index.html index.htm;
   }
   // 即访问http://localhost:80/ nginx 会去查找/var/html/index.html
   

   5.4. reload nginx

   nginx -s reload
   

   5.5. 访问文档

   http://localhost/