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（）的参数名称已被注释掉，因为它没有在基类的该方法实现中使用，我们希望避免使用unused-argument编译器警告。

这一切都很好，但是当我在代码库上运行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

...因为它当然没有看到注释掉的参数名称＆＃34;值＆＃34;在BaseClass :: SomeVirtualMethod（）声明中。所有这些警告使我很难找到并修复＆＃34;真正的＆＃34;由错别字等引起的氧气警告

我的问题是，有没有办法让DOxygen来治疗这一行：

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

好像它等同于这个：

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

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

Answer 1

取消注释参数名称，然后添加（void）值

我会使用正确的UNUSED宏来使用该选项，因此您可以强制它可移植。

在创建文档时，DOxygen会替换宏吗？

如果是这样，您可以添加一个在编译时扩展为空的宏，并在创建文档时扩展为其参数。

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

使用快速正则表达式搜索替换至少更容易，但如果主要担心的是版本控制系统的占用空间，那么它仍然是一个问题。

Answer 2

Karoly的回答并不糟糕。这是另一种选择：只需定义虚拟功能的基本版本。当类只包含声明时，您可以在不收到警告的情况下命名参数，然后在定义中将其注释掉。

由于我们正在谈论虚拟功能，因此将其排除在外并不是内联的问题，很可能，如果是，您仍然可以在课外使用它，但标记为内联。但是将它放在.cpp而不是内联中有额外的好处，即为类提供一个关键函数，这为编译器提供了放置vtable的明确位置，从而减少了编译和链接时间。

如何让DOxygen使用并识别注释掉的参数名称？

2 个答案: