Document functions defined through a macro in Doxygen

Question

I have a class that does not really exist but is defined through a macro:

#define DEFCLASS(name,datatype) Class name { \
    public: \
        void clear(); \
        datatype obj; \
    };
DEFMETHOD(StringContainer, const char*)

...

StringContainer foo("hi!");

Of course it should have been implemented using templates but I didn't write it, I can't change it and a large codebase relies on it.

Now the question is, I would like to document StringContainer in doxygen. However, it's not a class that really exists, so if I do:

/*!
    \class StringContainer
    \brief A string container

    \fn void StringContainer::clear()
    \brief Clears the container
*/

I get doxygen warnings:

warning: documented function `StringContainer::clear' was not declared or defined.

And the documentation doesn't contain that function. I know it's a bit tricky, but is there any way to force doxygen to have "faith" and create the documentation for StringContainer even though it's not defined in the source code?

SOLUTION

It is possible to create fake .h files to make doxygen believe a class exists while preventing build systems from including it. Those files can have the .dox extension. This way, I'm going to create a .dox file including the class definition and the documentation:

class StringContainer {
public:
    /*! Removes the contents of the container. */
    void clear();
    const char *obj;
};

This file won't actually be included in the build system and its sole purpose will be for documenting StringContainer.

Answer 1

I had to do this a lot for an existing code base, and I found that using the "EXPAND_AS_DEFINED" configuration option will solve this for you. In your Doxygen configuration file, set the following:

EXPAND_AS_DEFINED = DEFCLASS

This works as long as the file that contains the definition of "DEFCLASS" is an input to your Doxygen. (i.e. this will NOT work for things like "STDMETHOD" as you likely don't include the file that defines "STDMETHOD" as a Doxygen input)

I tried this out in VS 2010 as follows, and was able to both compile and run Doxygen without warnings.

Here is the example:

Base.h file:

#pragma once

#define DEFCLASS(name,datatype) class name { \
    public: \
        name(){} \
        void clear(){}; \
        datatype obj; \
    };

DEFCLASS(StringContainer, const char*)


/*!
    \class StringContainer
    \brief A string container

    \fn void StringContainer::clear()
    \brief Clears the container
*/

Base.cpp file:

#include "Base.h"

int main()
{
    StringContainer foo;
    foo.clear();


    return 0;
}

DoxygenTest.doxygen

MACRO_EXPANSION        = YES
EXPAND_ONLY_PREDEF     = YES
EXPAND_AS_DEFINED      = DEFCLASS

Answer 2

If you set MACRO_EXPANSION to "yes" in thé doxygen configuration (http://www.star.bnl.gov/public/comp/sofi/doxygen/config.htm)l doxygen will "see" StringContainer.