/****************************************************************************** * * $Id: preprocessing.doc,v 1.3 2001/03/19 19:27:39 root Exp $ * * Copyright (C) 1997-2001 by Dimitri van Heesch. * * Permission to use, copy, modify, and distribute this software and its * documentation under the terms of the GNU General Public License is hereby  * granted. No representations are made about the suitability of this software  * for any purpose. It is provided "as is" without express or implied warranty. * See the GNU General Public License for more details. * * Documents produced by Doxygen are derivative works derived from the * input used in their production; they are not affected by this license. * *//*! \page preprocessing PreprocessingSource files that are used as input to doxygen can be parsed by doxygen'sbuilt-in C-preprocessor.By default doxygen does only partial preprocessing. That is, it evaluates conditional compilation statements (like \#if) and evaluates macro definitions, but it does not perform macro expansion.So if you have the following code fragment\verbatim#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\endverbatimThen by default doxygen will feed the following to its parser:\verbatim#define VERSION#define CONST_STRING  static CONST_STRING version = "2.xx";\endverbatimYou can disable all preprocessing by setting \ref cfg_enable_preprocessing "ENABLE_PREPROCESSING" to \c NO in the configuation file. In the case above doxygen will then readsboth statements!In case you want to expand the \c CONST_STRING macro, you should set the\ref cfg_macro_expansion "MACRO_EXPANSION" tag in the config file to \c YES. Then the result after preprocessing becomes:\verbatim#define VERSION#define CONST_STRING  static const char * version = "1.xx";\endverbatimNote that doxygen will now expand \e all macro definitions (recursively if needed). This is often too much. Therefore, doxygen also allows you to expand only those defines that you explicitly specify. For this you have to set the \ref cfg_expand_only_predef "EXPAND_ONLY_PREDEF" tag to \c YESand specify the macro definitions after the \ref cfg_predefined "PREDEFINED" or \ref cfg_expand_as_defined "EXPAND_AS_DEFINED" tag.  As an example, suppose you have the following obfuscated code fragmentof an abstract base class called \c IUnknown:\verbatim/*! A reference to an IID */#ifdef __cplusplus#define REFIID const IID &#else#define REFIID const IID *#endif/*! The IUnknown interface */DECLARE_INTERFACE(IUnknown){  STDMETHOD(HRESULT,QueryInterface) (THIS_ REFIID iid, void **ppv) PURE;  STDMETHOD(ULONG,AddRef) (THIS) PURE;  STDMETHOD(ULONG,Release) (THIS) PURE;};\endverbatimwithout macro expansion doxygen will get confused, but we may not want to expand the REFIID macro, because it is documented and the user that reads the documentation should use it when implementing the interface.By setting the following in the config file:\verbatimENABLE_PREPROCESSING = YESMACRO_EXPANSION      = YESEXPAND_ONLY_PREDEF   = YESPREDEFINED           = "DECLARE_INTERFACE(name)=class name" \                       "STDMETHOD(result,name)=virtual result name" \                       "PURE= = 0" \                       THIS_= \                       THIS= \		       __cplusplus\endverbatimwe can make sure that the proper result is fed to doxygen's parser:\verbatim/*! A reference to an IID */#define REFIID/*! The IUnknown interface */class  IUnknown{  virtual  HRESULT   QueryInterface ( REFIID iid, void **ppv) = 0;  virtual  ULONG   AddRef () = 0;  virtual  ULONG   Release () = 0;};\endverbatimNote that the \ref cfg_predefined "PREDEFINED" tag accepts function like macro definitions(like \c DECLARE_INTERFACE ), normal macro substitutions (like \c PURE and \c THIS) and plain defines (like \c __cplusplus).Note also that preprocessor definitions that are normally defined automatically by the preprocessor (like \c __cplusplus), have to be defined by hand with doxygen's parser (this is done because these definesare often platform/compiler specific).In some cases you may want to substitute a macro name or function by something else without exposing the result to further macro substitution.You can do this but using the <code>:=</code> operator instead of <code>=</code>As an example suppose we have the following piece of code:\verbatim#define QList QListTclass QListT{};\endverbatimThen the only way to get doxygen interpret this as a class definitionfor class QList is to define:\verbatimPREDEFINED = QListT:=QList\endverbatimHere is an example provided by Valter Minute & Reyes Ponce that helps doxygen to wade through the boilerplate code in Microsoft's ATL & MFC libraries:\verbatimPREDEFINED           = "DECLARE_INTERFACE(name)=class name" \                       "STDMETHOD(result,name)=virtual result name" \                       "PURE= = 0" \                       THIS_= \                       THIS= \                       DECLARE_REGISTRY_RESOURCEID=// \                       DECLARE_PROTECT_FINAL_CONSTRUCT=// \                       "DECLARE_AGGREGATABLE(Class)= " \                       "DECLARE_REGISTRY_RESOURCEID(Id)= " \                       DECLARE_MESSAGE_MAP = \                       BEGIN_MESSAGE_MAP=/* \                       END_MESSAGE_MAP=*/// \                       BEGIN_COM_MAP=/* \                       END_COM_MAP=*/// \                       BEGIN_PROP_MAP=/* \                       END_PROP_MAP=*/// \                       BEGIN_MSG_MAP=/* \                       END_MSG_MAP=*/// \                       BEGIN_PROPERTY_MAP=/* \                       END_PROPERTY_MAP=*/// \                       BEGIN_OBJECT_MAP=/* \                       END_OBJECT_MAP()=*/// \                       DECLARE_VIEW_STATUS=// \                       "STDMETHOD(a)=HRESULT a" \                       "ATL_NO_VTABLE= " \                       "__declspec(a)= " \                       BEGIN_CONNECTION_POINT_MAP=/* \                       END_CONNECTION_POINT_MAP=*/// \                       "DECLARE_DYNAMIC(class)= " \                       "IMPLEMENT_DYNAMIC(class1, class2)= " \                       "DECLARE_DYNCREATE(class)= " \                       "IMPLEMENT_DYNCREATE(class1, class2)= " \                       "IMPLEMENT_SERIAL(class1, class2, class3)= " \                       "DECLARE_MESSAGE_MAP()= " \                       TRY=try \                       "CATCH_ALL(e)= catch(...)" \                       END_CATCH_ALL= \                       "THROW_LAST()= throw"\                       "RUNTIME_CLASS(class)=class" \                       "MAKEINTRESOURCE(nId)=nId" \                       "IMPLEMENT_REGISTER(v, w, x, y, z)= " \                       "ASSERT(x)=assert(x)" \                       "ASSERT_VALID(x)=assert(x)" \                       "TRACE0(x)=printf(x)" \                       "OS_ERR(A,B)={ #A, B }" \                       __cplusplus \                       "DECLARE_OLECREATE(class)= " \                       "BEGIN_DISPATCH_MAP(class1, class2)= " \                       "BEGIN_INTERFACE_MAP(class1, class2)= " \                       "INTERFACE_PART(class, id, name)= " \                       "END_INTERFACE_MAP()=" \                       "DISP_FUNCTION(class, name, function, result, id)=" \                       "END_DISPATCH_MAP()=" \                       "IMPLEMENT_OLECREATE2(class, name, id1, id2, id3, id4,\                        id5, id6, id7, id8, id9, id10, id11)="\endverbatimAs you can see doxygen's preprocessor is quite powerful, but if you wanteven more flexibility you can always write an input filter and specify it after the \ref cfg_input_filter "INPUT_FILTER" tag.If you are unsure what the effect of doxygen's preprocessing will beyou can run doxygen as follows:\verbatim  doxygen -d Preprocessor\endverbatimThis will instruct doxygen to dump the input sources to standard output afterpreprocessing has been done (Hint: set <code>QUIET = YES</code> and <code>WARNINGS = NO</code> in the configuration file to disable any other output).\htmlonlyGo to the <a href="external.html">next</a> section or return to the <a href="index.html">index</a>.\endhtmlonly*/