继承模板基类`ActorThread<MyActor>`时Doxygen警告的解决方法

问题场景 #

使用Doxygen 1.9.5生成代码文档时，由于配置将警告视为错误，以下警告阻断了编译流程：

Doxygen警告信息 #

Parsing file SomeApp/Application/CommActor.hpp:33: error: no uniquely matching class member found for 
    ActorThread< CommActor >
  Possible candidates:
    'SomeApp::Core::ActorThread< Runnable >::ActorThread()' at line 198 of file SomeApp/Core/ActorThread.hpp
    'SomeApp::Core::ActorThread< Runnable >::ActorThread(const ActorThread &)=delete' at line 313 of file SomeApp/Core/ActorThread.hpp

涉及的头文件代码（MyActor.hpp） #

#ifndef MYACTOR_HPP_
#define MYACTOR_HPP_

#include "SomeApp/Core/ActorThread.hpp"

namespace SomeApp {
namespace Application {

class MyActor : public Core::ActorThread<MyActor> {
public:

  using MessageToCGFDelegate = Core::Delegate<void(const Comm::MessageToCGF&)>;

public:

  MyActor() = delete;
  MyActor(Aclass comm);
  MyActor(const MyActor&) = delete;
  MyActor(MyActor&&) = delete;
  virtual ~MyActor() = default;

public:

  MyActor& operator=(const MyActor&) = delete;
  MyActor& operator=(MyActor&&) = delete;

private:

  friend Core::ActorThread<MyActor>;

private:

  Aclass m_comm;
};


} // namespace Application
} // namespace SomeApp

#endif // !MYACTOR_HPP_

///////////////////////////////////////////////////////////////////////////////
// DOCUMENTATION                                                             //
///////////////////////////////////////////////////////////////////////////////

/** \addtogroup System
 *  @{
 */

/**
 * @class SomeApp::Application::MyActor
 *
 * @brief Actor containing the communication plugin.
 */

/** @}*/

问题原因 #

Doxygen在解析模板基类Core::ActorThread<MyActor>时，无法准确关联到该模板实例化后的成员，产生匹配歧义——它误将基类的模板参数Runnable和当前类的实例化参数混淆，导致找不到唯一匹配的构造函数。

解决方法 #

方法1：在类文档中显式指定继承关系 #

修改MyActor的Doxygen注释，添加@extends标签明确基类的完整实例化类型，帮助Doxygen正确识别继承关系：

/**
 * @class SomeApp::Application::MyActor
 * @extends SomeApp::Core::ActorThread<SomeApp::Application::MyActor>
 * @brief Actor containing the communication plugin.
 */

方法2：完善基类模板的文档 #

在ActorThread.hpp中，为模板类的构造函数添加清晰的文档注释，确保Doxygen能正确解析模板实例化后的成员：

/**
 * @brief 默认构造函数（已删除）
 */
ActorThread() = delete;

/**
 * @brief 拷贝构造函数（已删除）
 */
ActorThread(const ActorThread&) = delete;

方法3：调整Doxygen配置项 #

在Doxygen配置文件中，将TEMPLATE_RELATIONS设置为YES，开启模板类的关系解析支持：

TEMPLATE_RELATIONS = YES

方法4：检查文件名一致性 #

警告中提到的是CommActor.hpp，但提供的代码文件是MyActor.hpp，确认是否存在文件名拼写错误，或者Doxygen配置中误指向了错误的文件路径。

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