doc/preprocessing.doc

   1 /******************************************************************************
   2  *
   3  *
   4  *
   5  * Copyright (C) 1997-2015 by Dimitri van Heesch.
   6  *
   7  * Permission to use, copy, modify, and distribute this software and its
   8  * documentation under the terms of the GNU General Public License is hereby
   9  * granted. No representations are made about the suitability of this software
  10  * for any purpose. It is provided "as is" without express or implied warranty.
  11  * See the GNU General Public License for more details.
  12  *
  13  * Documents produced by Doxygen are derivative works derived from the
  14  * input used in their production; they are not affected by this license.
  15  *
  16  */
  17 /*! \page preprocessing Preprocessing
  18
  19 Source files that are used as input to doxygen can be parsed by doxygen's
  20 built-in C-preprocessor.
  21
  22 By default doxygen does only partial preprocessing. That is, it
  23 evaluates conditional compilation statements (like \c \#if) and
  24 evaluates macro definitions, but it does not perform macro expansion.
  25
  26 So if you have the following code fragment
  27 \verbatim
  28 #define VERSION 200
  29 #define CONST_STRING const char *
  30
  31 #if VERSION >= 200
  32   static CONST_STRING version = "2.xx";
  33 #else
  34   static CONST_STRING version = "1.xx";
  35 #endif
  36 \endverbatim
  37
  38 Then by default doxygen will feed the following to its parser:
  39
  40 \verbatim
  41 #define VERSION
  42 #define CONST_STRING
  43
  44   static CONST_STRING version = "2.xx";
  45 \endverbatim
  46
  47 You can disable all preprocessing by setting
  48 \ref cfg_enable_preprocessing "ENABLE_PREPROCESSING" to \c
  49 NO in the configuration file. In the case above doxygen will then read
  50 both statements, i.e.:
  51
  52 \verbatim
  53   static CONST_STRING version = "2.xx";
  54   static CONST_STRING version = "1.xx";
  55 \endverbatim
  56
  57 In case you want to expand the \c CONST_STRING macro, you should set the
  58 \ref cfg_macro_expansion "MACRO_EXPANSION" tag in the config file
  59 to \c YES. Then the result after preprocessing becomes:
  60
  61 \verbatim
  62 #define VERSION
  63 #define CONST_STRING
  64
  65   static const char * version = "2.xx";
  66 \endverbatim
  67
  68 Note that doxygen will now expand \e all macro definitions
  69 (recursively if needed). This is often too much. Therefore, doxygen also
  70 allows you to expand only those defines that you explicitly
  71 specify. For this you have to set the
  72 \ref cfg_expand_only_predef "EXPAND_ONLY_PREDEF" tag to \c YES
  73 and specify the macro definitions after
  74 the \ref cfg_predefined "PREDEFINED" or
  75 \ref cfg_expand_as_defined "EXPAND_AS_DEFINED" tag.
  76
  77 A typically example where some help from the preprocessor is needed is
  78 when dealing with the language extension from Microsoft: \c __declspec. The same goes
  79 for GNU's \c \__attribute__ extension. Here is an example function.
  80
  81 \verbatim
  82 extern "C" void __declspec(dllexport) ErrorMsg( String aMessage,...);
  83 \endverbatim
  84
  85 When nothing is done, doxygen will be confused and see \c __declspec as
  86 some sort of function. To help doxygen one typically uses the following
  87 preprocessor settings:
  88
  89 \verbatim
  90 ENABLE_PREPROCESSING   = YES
  91 MACRO_EXPANSION        = YES
  92 EXPAND_ONLY_PREDEF     = YES
  93 PREDEFINED             = __declspec(x)=
  94 \endverbatim
  95
  96 This will make sure the \c __declspec(dllexport) is removed before doxygen
  97 parses the source code.
  98
  99 Similar settings can be used for removing \c \__attribute__ expressions from the input:
 100
 101 \verbatim
 102 ENABLE_PREPROCESSING   = YES
 103 MACRO_EXPANSION        = YES
 104 EXPAND_ONLY_PREDEF     = YES
 105 PREDEFINED             = __attribute__(x)=
 106 \endverbatim
 107
 108 For a more complex example, suppose you have the following obfuscated
 109 code fragment of an abstract base class called \c IUnknown:
 110
 111 \verbatim
 112 /*! A reference to an IID */
 113 #ifdef __cplusplus
 114 #define REFIID const IID &
 115 #else
 116 #define REFIID const IID *
 117 #endif
 118
 119
 120 /*! The IUnknown interface */
 121 DECLARE_INTERFACE(IUnknown)
 122 {
 123   STDMETHOD(HRESULT,QueryInterface) (THIS_ REFIID iid, void **ppv) PURE;
 124   STDMETHOD(ULONG,AddRef) (THIS) PURE;
 125   STDMETHOD(ULONG,Release) (THIS) PURE;
 126 };
 127 \endverbatim
 128
 129 without macro expansion doxygen will get confused, but we may not want to
 130 expand the \c REFIID macro, because it is documented and the user that reads
 131 the documentation should use it when implementing the interface.
 132
 133 By setting the following in the config file:
 134
 135 \verbatim
 136 ENABLE_PREPROCESSING = YES
 137 MACRO_EXPANSION      = YES
 138 EXPAND_ONLY_PREDEF   = YES
 139 PREDEFINED           = "DECLARE_INTERFACE(name)=class name" \
 140                        "STDMETHOD(result,name)=virtual result name" \
 141                        "PURE= = 0" \
 142                        THIS_= \
 143                        THIS= \
 144                        __cplusplus
 145 \endverbatim
 146
 147 we can make sure that the proper result is fed to doxygen's parser:
 148 \verbatim
 149 /*! A reference to an IID */
 150 #define REFIID
 151
 152 /*! The IUnknown interface */
 153 class  IUnknown
 154 {
 155   virtual  HRESULT   QueryInterface ( REFIID iid, void **ppv) = 0;
 156   virtual  ULONG   AddRef () = 0;
 157   virtual  ULONG   Release () = 0;
 158 };
 159 \endverbatim
 160
 161 Note that the \ref cfg_predefined "PREDEFINED" tag accepts function
 162 like macro definitions
 163 (like \c DECLARE_INTERFACE ), normal macro
 164 substitutions (like \c PURE and \c THIS) and plain
 165 defines (like \c __cplusplus).
 166
 167 Note also that preprocessor definitions that are normally defined
 168 automatically by the preprocessor (like \c __cplusplus), have to be defined
 169 by hand with doxygen's parser (this is done because these defines
 170 are often platform/compiler specific).
 171
 172 In some cases you may want to substitute a macro name or function by
 173 something else without exposing the result to further macro substitution.
 174 You can do this but using the <code>:=</code> operator instead of
 175 <code>=</code>
 176
 177 As an example suppose we have the following piece of code:
 178 \verbatim
 179 #define QList QListT
 180 class QListT
 181 {
 182 };
 183 \endverbatim
 184
 185 Then the only way to get doxygen interpret this as a class definition
 186 for class \c QList is to define:
 187 \verbatim
 188 PREDEFINED = QListT:=QList
 189 \endverbatim
 190
 191 Here is an example provided by Valter Minute and Reyes Ponce that helps
 192 doxygen to wade through the boilerplate code in Microsoft's ATL \& MFC
 193 libraries:
 194
 195 \verbatim
 196 PREDEFINED           = "DECLARE_INTERFACE(name)=class name" \
 197                        "STDMETHOD(result,name)=virtual result name" \
 198                        "PURE= = 0" \
 199                        THIS_= \
 200                        THIS= \
 201                        DECLARE_REGISTRY_RESOURCEID=// \
 202                        DECLARE_PROTECT_FINAL_CONSTRUCT=// \
 203                        "DECLARE_AGGREGATABLE(Class)= " \
 204                        "DECLARE_REGISTRY_RESOURCEID(Id)= " \
 205                        DECLARE_MESSAGE_MAP= \
 206                        BEGIN_MESSAGE_MAP=/* \
 207                        END_MESSAGE_MAP=*/// \
 208                        BEGIN_COM_MAP=/* \
 209                        END_COM_MAP=*/// \
 210                        BEGIN_PROP_MAP=/* \
 211                        END_PROP_MAP=*/// \
 212                        BEGIN_MSG_MAP=/* \
 213                        END_MSG_MAP=*/// \
 214                        BEGIN_PROPERTY_MAP=/* \
 215                        END_PROPERTY_MAP=*/// \
 216                        BEGIN_OBJECT_MAP=/* \
 217                        END_OBJECT_MAP()=*/// \
 218                        DECLARE_VIEW_STATUS=// \
 219                        "STDMETHOD(a)=HRESULT a" \
 220                        "ATL_NO_VTABLE= " \
 221                        "__declspec(a)= " \
 222                        BEGIN_CONNECTION_POINT_MAP=/* \
 223                        END_CONNECTION_POINT_MAP=*/// \
 224                        "DECLARE_DYNAMIC(class)= " \
 225                        "IMPLEMENT_DYNAMIC(class1, class2)= " \
 226                        "DECLARE_DYNCREATE(class)= " \
 227                        "IMPLEMENT_DYNCREATE(class1, class2)= " \
 228                        "IMPLEMENT_SERIAL(class1, class2, class3)= " \
 229                        "DECLARE_MESSAGE_MAP()= " \
 230                        TRY=try \
 231                        "CATCH_ALL(e)= catch(...)" \
 232                        END_CATCH_ALL= \
 233                        "THROW_LAST()= throw"\
 234                        "RUNTIME_CLASS(class)=class" \
 235                        "MAKEINTRESOURCE(nId)=nId" \
 236                        "IMPLEMENT_REGISTER(v, w, x, y, z)= " \
 237                        "ASSERT(x)=assert(x)" \
 238                        "ASSERT_VALID(x)=assert(x)" \
 239                        "TRACE0(x)=printf(x)" \
 240                        "OS_ERR(A,B)={ #A, B }" \
 241                        __cplusplus \
 242                        "DECLARE_OLECREATE(class)= " \
 243                        "BEGIN_DISPATCH_MAP(class1, class2)= " \
 244                        "BEGIN_INTERFACE_MAP(class1, class2)= " \
 245                        "INTERFACE_PART(class, id, name)= " \
 246                        "END_INTERFACE_MAP()=" \
 247                        "DISP_FUNCTION(class, name, function, result, id)=" \
 248                        "END_DISPATCH_MAP()=" \
 249                        "IMPLEMENT_OLECREATE2(class, name, id1, id2, id3, id4,\
 250                         id5, id6, id7, id8, id9, id10, id11)="
 251 \endverbatim
 252
 253 As you can see doxygen's preprocessor is quite powerful, but if you want
 254 even more flexibility you can always write an input filter and specify it
 255 after the \ref cfg_input_filter "INPUT_FILTER" tag.
 256
 257 If you are unsure what the effect of doxygen's preprocessing will be
 258 you can run doxygen as follows:
 259 \verbatim
 260   doxygen -d Preprocessor
 261 \endverbatim
 262 This will instruct doxygen to dump the input sources to standard output after
 263 preprocessing has been done (Hint: set <code>QUIET = YES</code> and
 264 <code>WARNINGS = NO</code> in the configuration file to disable any other
 265 output).
 266
 267 \htmlonly
 268 Go to the <a href="autolink.html">next</a> section or return to the
 269  <a href="index.html">index</a>.
 270 \endhtmlonly
 271
 272 */