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

How to get DOxygen to use and recognize commented-out argument names?

本文关键字：注释 参数 识别 DOxygen      更新时间：2023-10-16

我有一个大型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 %in", 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）值;，但我更喜欢不需要修改代码库的解决方案，因为有大量实例这种模式，我想最大限度地减少我的更改足迹。

Karoly的回答还不错。这里有一个替代方案：只需定义虚拟函数的基本版本即可。当类仅包含声明时，可以在不收到警告的情况下命名参数，然后在定义中将其注释掉。

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

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

我会选择那个选项...使用适当的UNUSED宏，因此您可以强制其可移植。

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

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

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

这至少可以通过快速正则表达式搜索替换更容易做到，但是如果您主要担心的是版本控制系统的足迹，那仍然是一个问题。

相关文章：