CODEWITHSUNDEEP
c++cdoxygen
Buğra Gedik
Buğra Gedik

Reputation: 724

How to have macros expanded by doxygen, but not documented as a define?

Say I have:

#define MY_MACRO(FOO) void FOO();

MY_MACRO(hi);
MY_MACRO(hey);
MY_MACRO(hello);

#undef MY_MACRO

I want the macros to be expanded by doxygen, which I am able to do by configuring it the right way:

ENABLE_PREPROCESSING   = YES
MACRO_EXPANSION        = YES
EXPAND_ONLY_PREDEF     = YES
EXPAND_AS_DEFINED      = MY_MACRO

This enables me to see the expanded result of the macros as documented APIs in the doxygen output (functions hi, hey, and hello). That is all good so far. But the problem is that, doxygen also documents MY_MACRO as a define. However, I do not want the clients of the API to know about MY_MACRO, since it is undefed and is not usable by them, and should not be visible to them.

I have EXTRACT_ALL = YES in my doxygen configuration and I do not want to change that. I have tried the following configuration without success:

PREDEFINED      = DOXYGEN_SKIP_FOR_USERS

With the following code:

#ifndef DOXYGEN_SKIP_FOR_USERS
#define MY_MACRO(FOO) void FOO();
#endif /*DOXYGEN_SKIP_FOR_USERS*/

MY_MACRO(hi);
MY_MACRO(hey);
MY_MACRO(hello);

#undef MY_MACRO

This hides the documentation of the define, but of course prevents the expansion, so I do not get the functions documented in the generated API.

I would appreciate your help.

Upvotes: 7

Views: 9069

Answers (1)

Jens Gustedt
Jens Gustedt

Reputation: 78953

Supposing that MY_ is the prefix that you are using consistently in your code :) I would use the prefix MY__ (two underscores) for internal macros and then put something like

EXCLUDE_SYMBOLS        = MY__*

in the Doxygen configuration file.

Edit: the double underscore inside symbols is reserved for C++ (not for C). So if you want to be compatible with C and C++ you should choose some other type of convention. Unfortunately a leading underscore is reserved, too, so _MY_ wouldn't do neither.

Upvotes: 9

Related Questions