不得不会的代码注释工具——doxygen
下载
官网下载二进制或者直接用yum或apt工具下载。
使用流程
注释规则
项目注释
- 项目注释块用于对项目进行描述,每个项目只出现一次,一般可以放在main.c主函数文件头部。对于其它类型的项目,置于定义项目入口函数的文件中。对于无入口函数的项目,比如静态库项目,置于较关键且不会被外部项目引用的文件中。
- 项目注释块以“/** @mainpage”开头,以“*/”结束。包含项目描述、及功能描述、用法描述、注意事项4个描述章节。
- 项目描述章节描述项目名称、作者、代码库目录、项目详细描述4项内容,建议采用HTML的表格语法进行对齐描述。
- 功能描述章节列举该项目的主要功能。
- 用法描述章节列举该项目的主要使用方法,主要针对动态库、静态库等会被其它项目使用的项目。对于其它类型的项目,该章节可省略。
- 注意事项章节描述该项目的注意事项、依赖项目等相关信息
/**@mainpage
* @section 项目详细描述
*
* @section 功能描述
*
* @section 用法描述
*
**********************************************************************************
*/
项目注释也可以使用markdown文件作为主页,通过指定md文件路径来配置。
USE_MDFILE_AS_MAINPAGE = doc/readme.md
若markdown文件里包含图片,可能会出现图片无法显示的情况,这个时候需先检查图片路径是否正确,同时还需要在doxyfile中添加图片路径方可显示。
IMAGE_PATH = ./doc/images
文件注释
/**
* @file 文件名
* @brief 简介
* @details 细节
* @mainpage 工程概览
* @author 作者
* @version 版本号
* @date 年-月-日
*/
全局常量/变量/宏定义/结构体定义/类定义的注释
/// 缓存大小
#define BUFSIZ 1024*4
#define BUFSIZ 1024*4 ///< 缓存大小
函数注释
/**
* @brief 函数简介
*
* @param 形参 参数说明
* @param 形参 参数说明
* @return 返回值说明
*/
reference
- https://blog.srefan.com/2020/05/doxygen-generate-docs/