vnfs/VES5.0/doxygen-1.8.12/html/preprocessing.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   2 <html xmlns="http://www.w3.org/1999/xhtml">
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
   5 <meta http-equiv="X-UA-Compatible" content="IE=9"/>
   6 <meta name="generator" content="Doxygen 1.8.12"/>
   7 <meta name="viewport" content="width=device-width, initial-scale=1"/>
   8 <title>Doxygen: Preprocessing</title>
   9 <link href="tabs.css" rel="stylesheet" type="text/css"/>
  10 <script type="text/javascript" src="jquery.js"></script>
  11 <script type="text/javascript" src="dynsections.js"></script>
  12 <link href="navtree.css" rel="stylesheet" type="text/css"/>
  13 <script type="text/javascript" src="resize.js"></script>
  14 <script type="text/javascript" src="navtreedata.js"></script>
  15 <script type="text/javascript" src="navtree.js"></script>
  16 <script type="text/javascript">
  17   $(document).ready(initResizable);
  18 </script>
  19 <link href="doxygen_manual.css" rel="stylesheet" type="text/css" />
  20 </head>
  21 <body>
  22 <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
  23 <div id="titlearea">
  24 <table cellspacing="0" cellpadding="0">
  25  <tbody>
  26  <tr style="height: 56px;">
  27   <td id="projectalign" style="padding-left: 0.5em;">
  28    <div id="projectname">Doxygen
  29    </div>
  30   </td>
  31  </tr>
  32  </tbody>
  33 </table>
  34 </div>
  35 <!-- end header part -->
  36 <!-- Generated by Doxygen 1.8.12 -->
  37 </div><!-- top -->
  38 <div id="side-nav" class="ui-resizable side-nav-resizable">
  39   <div id="nav-tree">
  40     <div id="nav-tree-contents">
  41       <div id="nav-sync" class="sync"></div>
  42     </div>
  43   </div>
  44   <div id="splitbar" style="-moz-user-select:none;"
  45        class="ui-resizable-handle">
  46   </div>
  47 </div>
  48 <script type="text/javascript">
  49 $(document).ready(function(){initNavTree('preprocessing.html','');});
  50 </script>
  51 <div id="doc-content">
  52 <div class="header">
  53   <div class="headertitle">
  54 <div class="title">Preprocessing </div>  </div>
  55 </div><!--header-->
  56 <div class="contents">
  57 <div class="textblock"><p>Source files that are used as input to doxygen can be parsed by doxygen's built-in C-preprocessor.</p>
  58 <p>By default doxygen does only partial preprocessing. That is, it evaluates conditional compilation statements (like <code>#if</code>) and evaluates macro definitions, but it does not perform macro expansion.</p>
  59 <p>So if you have the following code fragment </p><pre class="fragment">#define VERSION 200
  60 #define CONST_STRING const char *
  61
  62 #if VERSION &gt;= 200
  63   static CONST_STRING version = "2.xx";
  64 #else
  65   static CONST_STRING version = "1.xx";
  66 #endif
  67 </pre><p>Then by default doxygen will feed the following to its parser:</p>
  68 <pre class="fragment">#define VERSION
  69 #define CONST_STRING
  70
  71   static CONST_STRING version = "2.xx";
  72 </pre><p>You can disable all preprocessing by setting <a class="el" href="config.html#cfg_enable_preprocessing">ENABLE_PREPROCESSING</a> to <code>NO</code> in the configuration file. In the case above doxygen will then read both statements, i.e.:</p>
  73 <pre class="fragment">  static CONST_STRING version = "2.xx";
  74   static CONST_STRING version = "1.xx";
  75 </pre><p>In case you want to expand the <code>CONST_STRING</code> macro, you should set the <a class="el" href="config.html#cfg_macro_expansion">MACRO_EXPANSION</a> tag in the config file to <code>YES</code>. Then the result after preprocessing becomes:</p>
  76 <pre class="fragment">#define VERSION
  77 #define CONST_STRING
  78
  79   static const char * version = "1.xx";
  80 </pre><p>Note that doxygen will now expand <em>all</em> 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 <a class="el" href="config.html#cfg_expand_only_predef">EXPAND_ONLY_PREDEF</a> tag to <code>YES</code> and specify the macro definitions after the <a class="el" href="config.html#cfg_predefined">PREDEFINED</a> or <a class="el" href="config.html#cfg_expand_as_defined">EXPAND_AS_DEFINED</a> tag.</p>
  81 <p>A typically example where some help from the preprocessor is needed is when dealing with the language extension from Microsoft: <code>__declspec</code>. The same goes for GNU's <code>__attribute__</code> extension. Here is an example function.</p>
  82 <pre class="fragment">extern "C" void __declspec(dllexport) ErrorMsg( String aMessage,...);
  83 </pre><p>When nothing is done, doxygen will be confused and see <code>__declspec</code> as some sort of function. To help doxygen one typically uses the following preprocessor settings:</p>
  84 <pre class="fragment">ENABLE_PREPROCESSING   = YES
  85 MACRO_EXPANSION        = YES
  86 EXPAND_ONLY_PREDEF     = YES
  87 PREDEFINED             = __declspec(x)=
  88 </pre><p>This will make sure the <code>__declspec(dllexport)</code> is removed before doxygen parses the source code.</p>
  89 <p>Similar settings can be used for removing <code>__attribute__</code> expressions from the input:</p>
  90 <pre class="fragment">ENABLE_PREPROCESSING   = YES
  91 MACRO_EXPANSION        = YES
  92 EXPAND_ONLY_PREDEF     = YES
  93 PREDEFINED             = __attribute__(x)=
  94 </pre><p>For a more complex example, suppose you have the following obfuscated code fragment of an abstract base class called <code>IUnknown:</code> </p>
  95 <pre class="fragment">/*! A reference to an IID */
  96 #ifdef __cplusplus
  97 #define REFIID const IID &amp;
  98 #else
  99 #define REFIID const IID *
 100 #endif
 101
 102
 103 /*! The IUnknown interface */
 104 DECLARE_INTERFACE(IUnknown)
 105 {
 106   STDMETHOD(HRESULT,QueryInterface) (THIS_ REFIID iid, void **ppv) PURE;
 107   STDMETHOD(ULONG,AddRef) (THIS) PURE;
 108   STDMETHOD(ULONG,Release) (THIS) PURE;
 109 };
 110 </pre><p>without macro expansion doxygen will get confused, but we may not want to expand the <code>REFIID</code> macro, because it is documented and the user that reads the documentation should use it when implementing the interface.</p>
 111 <p>By setting the following in the config file:</p>
 112 <pre class="fragment">ENABLE_PREPROCESSING = YES
 113 MACRO_EXPANSION      = YES
 114 EXPAND_ONLY_PREDEF   = YES
 115 PREDEFINED           = "DECLARE_INTERFACE(name)=class name" \
 116                        "STDMETHOD(result,name)=virtual result name" \
 117                        "PURE= = 0" \
 118                        THIS_= \
 119                        THIS= \
 120                __cplusplus
 121 </pre><p>we can make sure that the proper result is fed to doxygen's parser: </p><pre class="fragment">/*! A reference to an IID */
 122 #define REFIID
 123
 124 /*! The IUnknown interface */
 125 class  IUnknown
 126 {
 127   virtual  HRESULT   QueryInterface ( REFIID iid, void **ppv) = 0;
 128   virtual  ULONG   AddRef () = 0;
 129   virtual  ULONG   Release () = 0;
 130 };
 131 </pre><p>Note that the <a class="el" href="config.html#cfg_predefined">PREDEFINED</a> tag accepts function like macro definitions (like <code>DECLARE_INTERFACE</code> ), normal macro substitutions (like <code>PURE</code> and <code>THIS</code>) and plain defines (like <code>__cplusplus</code>).</p>
 132 <p>Note also that preprocessor definitions that are normally defined automatically by the preprocessor (like <code>__cplusplus</code>), have to be defined by hand with doxygen's parser (this is done because these defines are often platform/compiler specific).</p>
 133 <p>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></p>
 134 <p>As an example suppose we have the following piece of code: </p><pre class="fragment">#define QList QListT
 135 class QListT
 136 {
 137 };
 138 </pre><p>Then the only way to get doxygen interpret this as a class definition for class <code>QList</code> is to define: </p><pre class="fragment">PREDEFINED = QListT:=QList
 139 </pre><p>Here is an example provided by Valter Minute and Reyes Ponce that helps doxygen to wade through the boilerplate code in Microsoft's ATL &amp; MFC libraries:</p>
 140 <pre class="fragment">PREDEFINED           = "DECLARE_INTERFACE(name)=class name" \
 141                        "STDMETHOD(result,name)=virtual result name" \
 142                        "PURE= = 0" \
 143                        THIS_= \
 144                        THIS= \
 145                        DECLARE_REGISTRY_RESOURCEID=// \
 146                        DECLARE_PROTECT_FINAL_CONSTRUCT=// \
 147                        "DECLARE_AGGREGATABLE(Class)= " \
 148                        "DECLARE_REGISTRY_RESOURCEID(Id)= " \
 149                        DECLARE_MESSAGE_MAP= \
 150                        BEGIN_MESSAGE_MAP=/* \
 151                        END_MESSAGE_MAP=*/// \
 152                        BEGIN_COM_MAP=/* \
 153                        END_COM_MAP=*/// \
 154                        BEGIN_PROP_MAP=/* \
 155                        END_PROP_MAP=*/// \
 156                        BEGIN_MSG_MAP=/* \
 157                        END_MSG_MAP=*/// \
 158                        BEGIN_PROPERTY_MAP=/* \
 159                        END_PROPERTY_MAP=*/// \
 160                        BEGIN_OBJECT_MAP=/* \
 161                        END_OBJECT_MAP()=*/// \
 162                        DECLARE_VIEW_STATUS=// \
 163                        "STDMETHOD(a)=HRESULT a" \
 164                        "ATL_NO_VTABLE= " \
 165                        "__declspec(a)= " \
 166                        BEGIN_CONNECTION_POINT_MAP=/* \
 167                        END_CONNECTION_POINT_MAP=*/// \
 168                        "DECLARE_DYNAMIC(class)= " \
 169                        "IMPLEMENT_DYNAMIC(class1, class2)= " \
 170                        "DECLARE_DYNCREATE(class)= " \
 171                        "IMPLEMENT_DYNCREATE(class1, class2)= " \
 172                        "IMPLEMENT_SERIAL(class1, class2, class3)= " \
 173                        "DECLARE_MESSAGE_MAP()= " \
 174                        TRY=try \
 175                        "CATCH_ALL(e)= catch(...)" \
 176                        END_CATCH_ALL= \
 177                        "THROW_LAST()= throw"\
 178                        "RUNTIME_CLASS(class)=class" \
 179                        "MAKEINTRESOURCE(nId)=nId" \
 180                        "IMPLEMENT_REGISTER(v, w, x, y, z)= " \
 181                        "ASSERT(x)=assert(x)" \
 182                        "ASSERT_VALID(x)=assert(x)" \
 183                        "TRACE0(x)=printf(x)" \
 184                        "OS_ERR(A,B)={ #A, B }" \
 185                        __cplusplus \
 186                        "DECLARE_OLECREATE(class)= " \
 187                        "BEGIN_DISPATCH_MAP(class1, class2)= " \
 188                        "BEGIN_INTERFACE_MAP(class1, class2)= " \
 189                        "INTERFACE_PART(class, id, name)= " \
 190                        "END_INTERFACE_MAP()=" \
 191                        "DISP_FUNCTION(class, name, function, result, id)=" \
 192                        "END_DISPATCH_MAP()=" \
 193                        "IMPLEMENT_OLECREATE2(class, name, id1, id2, id3, id4,\
 194                         id5, id6, id7, id8, id9, id10, id11)="
 195 </pre><p>As you can see doxygen's preprocessor is quite powerful, but if you want even more flexibility you can always write an input filter and specify it after the <a class="el" href="config.html#cfg_input_filter">INPUT_FILTER</a> tag.</p>
 196 <p>If you are unsure what the effect of doxygen's preprocessing will be you can run doxygen as follows: </p><pre class="fragment">  doxygen -d Preprocessor
 197 </pre><p> This will instruct doxygen to dump the input sources to standard output after preprocessing has been done (Hint: set <code>QUIET = YES</code> and <code>WARNINGS = NO</code> in the configuration file to disable any other output).</p>
 198 <p>
 199 Go to the <a href="autolink.html">next</a> section or return to the
 200  <a href="index.html">index</a>.
 201  </p>
 202 </div></div><!-- contents -->
 203 </div><!-- doc-content -->
 204 <!-- start footer part -->
 205 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
 206   <ul>
 207     <li class="footer">Generated by
 208     <a href="http://www.doxygen.org/index.html">
 209     <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.12 </li>
 210   </ul>
 211 </div>
 212 </body>
 213 </html>