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

Question

I've got a large C++ codebase that includes several thousand instances of this sort of thing:

#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

Note that the argument-name to SomeVirtualMethod() is commented out, because it isn't used in the base class's implementation of that method, and we want to avoid an unused-argument compiler warning.

That's all well and good, but when I run DOxygen (1.8.8) on the codebase, DOxygen outputs lots and lots of warnings like this:

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

... because of course it is not seeing the commented-out parameter name "value" in the BaseClass::SomeVirtualMethod() declaration. All of these warnings make it difficult for me to find and fix the "real" DOxygen warnings caused by typos, etc.

My question is, is there any way to get DOxygen to treat this line:

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

as if it were equivalent to this one:

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

for documentation-generating purposes? (I know there are ways to modify the code, such as un-commenting the parameter name and then adding a (void) value; into the method-body, but I'd prefer a solution that does not require modifying the codebase as there are a large number of instances of this pattern and I'd like to minimize my changes-footprint.

Answer 1

un-commenting the parameter name and then adding a (void) value

I would go with that option... with the proper UNUSED macro, so you can force it to be portable.

Does DOxygen substitute macros when creating the documentation?

If so, you could add a macro that expands to nothing when compiling, and expands to its argument when creating the documentation.

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

This is at least easier to do with a quick regex search-replace, but if your main worry is the footprint on version control system, it is still a problem.

Answer 2

Karoly's answer isn't bad. Here's an alternative: just define the base version of the virtual function out of line. When the class contains only a declaration, you can name the parameter without getting a warning, and then comment it out in the definition.

Since we're talking virtual functions, having it out of line isn't a problem for inlining, most likely, and if it is, you can still have it outside the class but marked as inline. But having it in a .cpp and not inline has the additional benefit of providing a key function for the class, which gives the compiler a definite place to put the vtable, thus reducing compile and linking time a bit.