Doxygen使用介绍

Doxygen的主页为http://doxygen.nl/,它的license为GPL,最新发布版本为1.8.17,源代码存放在https://github.com/doxygen/doxygen,它支持的语言包括C、C++、Objective-C、C#、Java、Python等,它支持的系统平台包括Winodws、Linux、MacOS等。你既可以通过源码编译安装,也可以直接通过二进制文件安装,可从http://www.doxygen.nl/download.html 直接下载二进制文件。

Doxygen是文档生成工具,用于从带注释的C++等语言源码中生成文档。它可产生的文档格式包括HTML、LaTex、xml等。该文档直接从源代码中提取,这使得文档和源代码保持一致变得很容易。你可以配置Doxygen使其从未记录的源文件中提取代码结构(You can configure doxygen to extract the code structure from undocumented source files)。Doxygen还可以通过包括依赖图、继承图和协助图来可视化各个元素直接的关系,所有这些图都是自动生成的。你也可以使用Doxygen来创建常规文档。

Doxygen使用步骤:

(1). 以下以Windows平台为例,介绍其使用,这里主要关心怎么生成文档,不关心其code实现,因此直接下载二进制文件doxygen-1.8.17-setup.exe进行安装。安装过程中不需要什么特别设置,默认即可。安装完后,打开命令提示符,输入doxygen.exe,执行结果如下,说明已正确安装:安装完后,在指定的安装目录下会有一个doxygen_manual.chm文件,此文件为用户手册,供大家查询相关信息。

Doxygen使用介绍_第1张图片

(2). 生成doxygen配置文件:Doxygen使用配置文件来确定其所有设置。每一个项目应该设置它自己的配置文件。为了简化配置文件的创建,Doxygen可以为你创建一个模板配置文件。通过执行doxygen.exe -y或doxygen.exe -y xxx,其中xxx为配置文件的名字,如果不指定,则默认生成的配置文件名字为Doxyfile,执行结果如下:

Doxygen使用介绍_第2张图片

生成的Doxyfile文件有2000多行,可通过文本编辑器打开它。配置文件的格式类似于简单的Makefile的格式,它由许多标签(tag)组成,大多数标签都给了其默认值,可根据自己实际需要进行修改。每个标签的用法可在doxygen_manual.chm中查找,而且Doxyfile中也给出了描述。这里仅列出几个用到的需要修改默认值的标签:

PROJECT_NAME        = "Doxygen_Test"
INPUT               = E:/GitCode/Doxygen_Test
FILE_PATTERNS       = *.hpp *.cpp
RECURSIVE           = YES
OUTPUT_DIRECTORY    = E:/GitCode/Doxygen_Test
GENERATE_LATEX      = NO
INPUT_ENCODING      = GB2312

设置好后的Doxyfile文件部分内容如下:

Doxygen使用介绍_第3张图片

(3). 以C++为例,编写测试code,按照doxygen支持的格式添加注释,所有的文件全部存放在E:/GitCode/Doxygen_Test目录下,doxygen支持的注释示例可参考安装目录下的examples目录或doxygen_manual.chm,测试代码头文件api.hpp内容如下:

#ifndef FBC_DOXYGEN_TEST_
#define FBC_DOXYGEN_TEST_

/// @file api.hpp
/// @brief 以下所有的声明全部在命名空间fbc内
/// @author fengbingchun
/// @version 1.0.0
/// @date 2020-03-08
/// @copyright MIT
/// @since 仅作为测试用,无任何实际意义
namespace fbc {

/// 设置缓存大小
#define BUFSIZE		1024 * 3

/// @brief 矩形定义
typedef struct fbc_rect{
	int width;	///< 矩形宽
	int height;	///< 矩形高
} fbc_rect;

/// @brief 人脸识别类
/// @details 输入一张图像,返回检测到人脸图像框位置
/// @attention 仅支持输入bgr 3通道图像,仅支持检测一张人脸
class FaceRecognition {
public:
	FaceRecognition() = default; ///< 默认构造函数

	/// @brief 带参数的构造函数
	/// @param[in] data 图像数据首地址
	/// @param[in] width 图像宽
	/// @param[in] height 图像高
	/// @bug 内部没有对参数进行判断
	FaceRecognition(unsigned char* data, int width, int height);

	/// @brief 人脸检测
	/// @param[out] rect 检测到的人脸
	/// @return 正常返回0,否则返回错误码
	int Run(fbc_rect& rect);

private:
	unsigned char* data_;	///< 图像数据
	int width;		///< 图像宽
	int height;		///< 图像高
};

/**
 * @brief 加操作
 * @attention 并没有对输入参数进行判断
 * @param[in] rect1 矩形大小
 * @param[in] rect2 矩形大小
 * @param[out] rect3 计算结果
 * @return 正常执行返回0,否则返回错误码
*/
int fbc_add(const fbc_rect& rect1, const fbc_rect& rect2, fbc_rect& rect3);

/// @brief 人脸检测
/// @warning 内部并没有判断是否溢出
/// @see https://blog.csdn.net/fengbingchun
/// @return 正常执行返回0,否则返回错误码
int fbc_face_detect();

} // namespace fbc

#endif // FBC_DOXYGEN_TEST_

(4). 生成文档:执行doxygen.exe Doxyfile,执行结果如下:

Doxygen使用介绍_第4张图片

执行完后会在E:/GitCode/Doxygen_Test目录下产生一个html目录,打开里面的任一html文件,如api_8hpp.html结果如下:

Doxygen使用介绍_第5张图片

 

你可能感兴趣的:(Linux,Windows7/10,Mac)