Source files which are used as input to DoxyPress can be parsed by the built in preprocessor. By default DoxyPress only partially preprocesses defines and macros. The preprocessor evaluates conditional compilation statements and macro definitions, however it does not perform macro expansion.

As an example, suppose the following fragment exists in a source file.

#define VERSION 200
#define CONST_STRING const char *

#if VERSION >= 200
  static CONST_STRING version = "2.xx";
#else
  static CONST_STRING version = "1.xx";
#endif

Preprocessing Enabled

By default DoxyPress will parse the following lines.

#define VERSION
#define CONST_STRING

  static CONST_STRING version = "2.xx";

Preprocessing Disabled

In this example DoxyPress will read both statements.

#define VERSION
#define CONST_STRING

  static CONST_STRING version = "2.xx";
  static CONST_STRING version = "1.xx";

Preprocessing Enabled, Macro Expansion Enabled

To expand the CONST_STRING macro, the macro-expansion tag in the project file must be enabled. Then the result after preprocessing would be as follows.

#define VERSION
#define CONST_STRING

  static const char * version = "2.xx";

Macro Expansion

DoxyPress expands all macro definitions (recursively if needed) which is often not desired. In order to limit which macro expansions occur, set the expand-only-predefined tag to YES and list the macros definitions to be expanded in the predefined-macros tag or the macro names in the expand-as-defined tag.

As an example, this feature is useful to hide non standard syntax from the DoxyPress parser. In the following declaration __declspec(dllexport) is required by Windows to export this function. If this syntax is visible to the DoxyPress parser, it will read this line as a declaration of a function named __declspec, which is not what the source code means.

   void __declspec(dllexport) ErrorMsg(String aMessage, ...);

The following tag settings will result in this syntax being removed during preprocessing in DoxyPress.

ENABLE-PREPROCESSING    = YES
MACRO-EXPANSION         = YES
EXPAND-ONLY-PREDEFINED  = YES
PREDEFINED-MACROS       = __declspec(x)=

Preprocessor

Preprocessor definitions which are normally defined by your compiler are not available to DoxyPress. Macros like __cplusplus may need to be defined in your project file.

ENABLE-PREPROCESSING    = YES
MACRO-EXPANSION         = YES
PREDEFINED-MACROS       = __cplusplus=, _MSC_VER=1914, __GNUC__=7

Substitution

In some cases it may be necessary to expand only one level of macro expansion and not expand it recursively. To do this, use a "colon equal" operator instead of an "equal" operator in the PREDEFINED-MACROS tag.

As an example suppose we have the following source in a header file.

#define  MyClass  internal_MyClass

class internal_MyClass;

If the equal operator is used in the predefined macro expansion, the output might look something like the following, which is not not the desired result.

class internal_internal_internal_...

To avoid this recursive problem use the following syntax in your project file.

ENABLE-PREPROCESSING    = YES
MACRO-EXPANSION         = YES
PREDEFINED-MACROS       = MyClass:=internal_MyClass

Input Filter

To add more flexibility to the DoxyPress preprocessor you can write an input filter and specify the path to your filter in the filter-program tag.