如何用Doxygen标注含requires子句与static_assert的函数模板文档？

假设C++标准中存在std::frobnicate函数模板，其规范如下：

template <class T>
void frobnicate(T t);

• Requires: widget<T>为true（该重载仅适用于满足widget概念的类型，等价于用requires widget<T>约束函数）
• Mandates: sprocket<T>为false（若以满足sprocket的类型调用该函数，程序非法，等价于函数体内的static_assert(!sprocket<T>)）

由于Doxygen没有原生的@requires或@mandates命令，可通过以下几种实用方式实现两者的区分：

1. 自定义Doxygen命令 #

修改Doxygen配置文件（Doxyfile）中的ALIASES选项，为两种约束创建专属别名：

ALIASES += "requires=@par Requires:\n"
ALIASES += "mandates=@par Mandates:\n"

之后在代码注释中直接使用，生成的文档会将两者作为独立段落展示：

/**
 * @brief 对给定对象执行frobnicate操作
 * @tparam T 操作的对象类型
 * @requires `widget<T>`必须为true
 * @mandates `sprocket<T>`必须为false
 * @param t 要操作的对象
 */
template <class T>
requires widget<T>
void frobnicate(T t) {
    static_assert(!sprocket<T>, "T must not satisfy sprocket concept");
    // 函数实现
}

2. 使用@par标签手动划分段落 #

无需修改配置，直接用@par定义带标题的段落，明确区分两种约束：

/**
 * @brief 对给定对象执行frobnicate操作
 * @tparam T 操作的对象类型
 * @par Requires:
 * `widget<T>`必须为true（仅适用于满足widget概念的类型）
 * @par Mandates:
 * `sprocket<T>`必须为false（若使用满足sprocket的类型调用，程序非法）
 * @param t 要操作的对象
 */
template <class T>
requires widget<T>
void frobnicate(T t) {
    static_assert(!sprocket<T>, "T must not satisfy sprocket concept");
    // 函数实现
}

3. 结合@note和@warning标注语义差异 #

利用两者的语义区别强调约束的不同性质：

• @note用于标注Requires（调用前需满足的前置条件）
• @warning用于标注Mandates（编译期强制要求，违反会直接导致程序非法）

/**
 * @brief 对给定对象执行frobnicate操作
 * @tparam T 操作的对象类型
 * @note Requires: `widget<T>`必须为true，仅适用于满足widget概念的类型
 * @warning Mandates: `sprocket<T>`必须为false，若使用满足sprocket的类型调用，程序将非法
 * @param t 要操作的对象
 */
template <class T>
requires widget<T>
void frobnicate(T t) {
    static_assert(!sprocket<T>, "T must not satisfy sprocket concept");
    // 函数实现
}

4. 在@tparam描述中集中说明约束 #

将两种约束直接嵌入模板参数的描述中，让读者快速关联类型要求：

/**
 * @brief 对给定对象执行frobnicate操作
 * @tparam T 操作的对象类型，必须满足：
 *           - Requires: `widget<T>`为true（仅适用于满足widget概念的类型）
 *           - Mandates: `sprocket<T>`为false（违反会导致编译错误）
 * @param t 要操作的对象
 */
template <class T>
requires widget<T>
void frobnicate(T t) {
    static_assert(!sprocket<T>, "T must not satisfy sprocket concept");
    // 函数实现
}

内容的提问来源于stack exchange，提问作者Eric Niebler