Doxygen1.9.1下CRTP派生类继承的接口函数如何追加专属文档

实现方案 #

你可以通过在派生类中添加using声明关联Doxygen文档的方式实现需求，完全不需要修改原有CRTP逻辑，也不会引入额外代码开销。

示例修改代码 #

template <class D>
class CommonInterface
{
public:
    /**
    \brief My common function description.
    */
    void foo()
    {
        static_cast<D*>(this)->foo_impl();
    }
};

class A : public CommonInterface<A>
{
public:
    A() = default;

    /**
    \copydoc CommonInterface<D>::foo()
    \details 此处补充仅A类foo接口可见的专属说明，比如特化版本的行为差异、使用限制等，这部分内容不会出现在CommonInterface基类的文档中。
    */
    using CommonInterface<A>::foo;

private:
    void foo_impl() {};

    friend class CommonInterface<A>;
};

生效说明 #

保持Doxygen默认配置项EXTRACT_INHERITED_MEMB = YES（默认状态为启用）即可正常生效，Doxygen会自动将using声明关联的文档和继承的foo()方法合并，不会生成重复的方法条目。

方案符合要求的特性 #

• 完全没有覆写基类foo()方法，保留CRTP的所有设计逻辑，无任何运行时开销
• 不需要为私有接口foo_impl()编写公开文档，所有对外说明都集中在公开的foo()接口上
• 基类CommonInterface的原有文档完全不受影响，补充内容仅在派生类A的文档中展示

内容的提问来源于stack exchange，提问作者Tom de Geus