1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.12"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Doxygen: Preprocessing</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
</script>
<link href="doxygen_manual.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">Doxygen
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.12 -->
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('preprocessing.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">Preprocessing </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Source files that are used as input to doxygen can be parsed by doxygen's built-in C-preprocessor.</p>
<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>
<p>So if you have the following code fragment </p><pre class="fragment">#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
</pre><p>Then by default doxygen will feed the following to its parser:</p>
<pre class="fragment">#define VERSION
#define CONST_STRING
static CONST_STRING version = "2.xx";
</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>
<pre class="fragment"> static CONST_STRING version = "2.xx";
static CONST_STRING version = "1.xx";
</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>
<pre class="fragment">#define VERSION
#define CONST_STRING
static const char * version = "1.xx";
</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>
<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>
<pre class="fragment">extern "C" void __declspec(dllexport) ErrorMsg( String aMessage,...);
</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>
<pre class="fragment">ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
PREDEFINED = __declspec(x)=
</pre><p>This will make sure the <code>__declspec(dllexport)</code> is removed before doxygen parses the source code.</p>
<p>Similar settings can be used for removing <code>__attribute__</code> expressions from the input:</p>
<pre class="fragment">ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
PREDEFINED = __attribute__(x)=
</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>
<pre class="fragment">/*! 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;
};
</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>
<p>By setting the following in the config file:</p>
<pre class="fragment">ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
PREDEFINED = "DECLARE_INTERFACE(name)=class name" \
"STDMETHOD(result,name)=virtual result name" \
"PURE= = 0" \
THIS_= \
THIS= \
__cplusplus
</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 */
#define REFIID
/*! The IUnknown interface */
class IUnknown
{
virtual HRESULT QueryInterface ( REFIID iid, void **ppv) = 0;
virtual ULONG AddRef () = 0;
virtual ULONG Release () = 0;
};
</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>
<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>
<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>
<p>As an example suppose we have the following piece of code: </p><pre class="fragment">#define QList QListT
class QListT
{
};
</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
</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 & MFC libraries:</p>
<pre class="fragment">PREDEFINED = "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)="
</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>
<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
</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>
<p>
Go to the <a href="autolink.html">next</a> section or return to the
<a href="index.html">index</a>.
</p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.12 </li>
</ul>
</div>
</body>
</html>
|
