Doxygen 文档生成系统标签详解-CSDN博客

本文链接：https://blog.csdn.net/qq_43689451/article/details/147952845

Doxygen 文档生成系统标签详解

Doxygen 是一个功能强大的文档生成工具，主要用于C++、C、Java等编程语言。通过在代码中添加特定格式的注释，Doxygen可以自动生成完整的API文档。以下是Doxygen常用标签的详细说明：

基本注释格式

Doxygen支持多种注释格式：

/**
 * JavaDoc风格（推荐用于多行注释）
 */

/// 三斜线风格（适合单行注释）

//! Qt风格注释

/*!
 * Qt风格多行注释
 */

常用标签

基本描述标签

标签	说明	示例
`@brief`	简要描述	`@brief 这是一个字符串处理函数`
`@details`	详细描述	`@details 本函数实现了高效的字符串分割算法`
`@author`	作者信息	`@author 张三 <zhang@example.com>`
`@version`	版本信息	`@version 1.0.2`
`@date`	日期	`@date 2025-05-14`
`@note`	注意事项	`@note 此函数不是线程安全的`
`@warning`	警告信息	`@warning 参数必须非空，否则会导致崩溃`

函数相关标签

标签	说明	示例
`@param`	参数说明	`@param[in] name 用户名称`
`@param[in]`	输入参数	`@param[in] data 输入数据`
`@param[out]`	输出参数	`@param[out] result 计算结果`
`@param[in,out]`	既是输入也是输出的参数	`@param[in,out] buffer 数据缓冲区`
`@return`	返回值说明	`@return 处理后的字符串`
`@retval`	特定返回值说明	`@retval nullptr 如果输入无效`
`@throws`	可能抛出的异常	`@throws std::invalid_argument 参数无效时`

关系标签

标签	说明	示例
`@see`	参见其他内容	`@see OtherClass::method()`
`@sa`	参见(同@see)	`@sa relatedFunction()`
`@relates`	关联到某个类	`@relates ClassName`
`@ingroup`	指定所属组	`@ingroup Utilities`

代码示例与测试

标签	说明	示例
`@code`	开始代码示例	`@code`
`@endcode`	结束代码示例	`@endcode`
`@example`	引用示例文件	`@example test.cpp`
`@snippet`	插入代码片段	`@snippet example.cpp mysnippet`
`@test`	测试说明	`@test 此功能已通过单元测试验证`

文件和模块标签

标签	说明	示例
`@file`	文件说明	`@file utils.h`
`@dir`	目录说明	`@dir include/utilities`
`@package`	包/命名空间说明	`@package com.example.util`
`@namespace`	命名空间说明	`@namespace utils`
`@headerfile`	头文件说明	`@headerfile <string>`

特殊功能标签

标签	说明	示例
`@todo`	待办事项	`@todo 优化算法效率`
`@bug`	已知问题	`@bug 在Windows XP下可能崩溃`
`@deprecated`	标记为已废弃	`@deprecated 从v2.0起不再支持，请使用newFunction()`
`@since`	可用版本	`@since v1.5`
`@internal`	内部使用说明	`@internal 仅供内部调用，不属于公开API`
`@private`	私有内容	`@private`

完整示例

/**
 * @file StringUtils.h
 * @brief 字符串处理工具类
 * @author 李四 <li@example.com>
 * @date 2025-05-14
 */

/**
 * @namespace utils
 * @brief 通用工具命名空间
 */
namespace utils {

/**
 * @class StringUtils
 * @brief 提供字符串处理的各种实用功能
 * @details 这个类封装了常见的字符串操作，包括分割、替换、转换等功能，
 *          设计为静态方法集合，不需要实例化。
 * @note 所有方法都是线程安全的
 */
class StringUtils {
public:
    /**
     * @brief 分割字符串为字符串数组
     * @param[in] str 要分割的字符串
     * @param[in] delimiter 分隔符
     * @return 分割后的字符串数组
     * 
     * @throws std::invalid_argument 如果输入字符串为空
     * 
     * @code
     * auto result = StringUtils::split("a,b,c", ",");
     * // result包含 ["a", "b", "c"]
     * @endcode
     * 
     * @see join() 字符串数组合并方法
     * @since v1.2
     */
    static std::vector<std::string> split(const std::string& str, const std::string& delimiter);
    
    /**
     * @brief 将字符串转换为大写
     * @param[in] str 输入字符串
     * @return 转换后的大写字符串
     * 
     * @warning 此方法不处理Unicode字符
     * @todo 添加Unicode支持
     * @deprecated 从v2.0起请使用toUpperUtf8()方法
     */
    static std::string toUpper(const std::string& str);
};

} // namespace utils