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.

bds14 · Accepted Answer · 2012-08-02 12:50:48Z

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

Éric Malenfant · Accepted Answer · 2012-05-11 11:49:12Z

1

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.

answered May 11, 2012 at 11:49

Éric Malenfant

14.2k42 silver badges42 bronze badges

1 Comment

Víctor Fernández Over a year ago

Thanks. That makes doxygen find the methods. Unfortunatly that does not replace datatype with const char * in the given example.

David Maze · Accepted Answer · 2025-11-12 12:38:03Z

-1

I suggest to read the Preprocessing section of the doxygen manual. The part where it is explained how to deal with DECLARE_INTERFACE and STDMETHOD macros is very similar to what you want.

So this can be an alternative solution, in case you do not wish to write a dummy class in a separate file.

edited Nov 12 at 12:38

David Maze

165k47 gold badges262 silver badges302 bronze badges

answered May 12, 2012 at 8:03

doxygen

15k2 gold badges45 silver badges40 bronze badges

Collectives™ on Stack Overflow

Document functions defined through a macro in Doxygen

3 Answers 3

Base.h file:

Base.cpp file:

DoxygenTest.doxygen

Comments

1 Comment

Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

3 Answers 3

Base.h file:

Base.cpp file:

DoxygenTest.doxygen

Comments

1 Comment

Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related