c++ - 如何让 DOxygen 使用和识别注释掉的参数名称？

Question

我有一个大型 C++ 代码库，其中包含数千个此类实例:

#ifndef SOME_HEADER_FILE_H
#define SOME_HEADER_FILE_H

/** This is a base class, meant to be subclassed by other classes */
class BaseClass
{
public:
    /** Can be overridden to do something useful.  Default implementation is a no-op.
      * @param value The value to work with.
      */
    virtual void SomeVirtualMethod(int /*value*/) {/* empty */}
};

/** This class adds some functionality to BaseClass */
class DerivedClass : public BaseClass
{
public:
    virtual void SomeVirtualMethod(int value) {printf("value is %i\n", value);}
};

#endif

请注意，SomeVirtualMethod() 的参数名称已被注释掉，因为它未在该方法的基类实现中使用，我们希望避免出现未使用参数编译器警告。

一切都很好，但是当我在代码库上运行 DOxygen (1.8.8) 时，DOxygen 会输出很多很多这样的警告:

Generating docs for compound BaseClass...
/Users/jaf/temp.h:9: warning: argument 'value' of command @param is not found in the argument list of BaseClass::SomeVirtualMethod(int)
Generating docs for compound DerivedClass...
/Users/jaf/temp.h:18: warning: argument 'value' of command @param is not found in the argument list of DerivedClass::SomeVirtualMethod(int) inherited from member SomeVirtualMethod at line 9 in file /Users/jaf/crap/temp.h

... 因为它当然没有在 BaseClass::SomeVirtualMethod() 声明中看到注释掉的参数名称“value”。所有这些警告让我很难找到并修复由拼写错误等引起的“真正的”DOxygen 警告。

我的问题是，有什么方法可以让 DOxygen 处理这条线路:

virtual void SomeVirtualMethod(int /*value*/) {/* empty */}

就好像它等同于这个:

virtual void SomeVirtualMethod(int value) {/* empty */}

为了文档生成的目的？ (我知道有一些方法可以修改代码，例如取消注释参数名称，然后添加一个 (void) 值；到方法体中，但我更喜欢不需要修改代码库的解决方案，因为那里有大量这种模式的实例，我想尽量减少我的更改足迹。

Answer 1

Karoly 的回答还不错。这里有一个替代方案:只定义虚函数的基础版本。当类只包含声明时，您可以命名参数而不得到警告，然后在定义中将其注释掉。

因为我们在谈论虚函数，所以它越界对内联来说不是问题，很可能，如果是，您仍然可以在类之外使用它，但将其标记为内联。但是将它放在 .cpp 中而不是内联还有一个额外的好处，即为类提供一个关键函数，这为编译器提供了放置 vtable 的明确位置，从而稍微减少了编译和链接时间。