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
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
|
/******************************************************************************
*
*
*
* Copyright (C) 1997-2015 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 Preprocessing
Source files that are used as input to doxygen can be parsed by doxygen's
built-in C-preprocessor.
By default doxygen does only partial preprocessing. That is, it
evaluates conditional compilation statements (like \c \#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
\endverbatim
Then by default doxygen will feed the following to its parser:
\verbatim
#define VERSION
#define CONST_STRING
static CONST_STRING version = "2.xx";
\endverbatim
You can disable all preprocessing by setting
\ref cfg_enable_preprocessing "ENABLE_PREPROCESSING" to \c
NO in the configuration file. In the case above doxygen will then read
both statements, i.e.:
\verbatim
static CONST_STRING version = "2.xx";
static CONST_STRING version = "1.xx";
\endverbatim
In case you want to expand the \c CONST_STRING macro, you should set the
\ref cfg_macro_expansion "MACRO_EXPANSION" tag in the configuration file
to \c YES. Then the result after preprocessing becomes:
\verbatim
#define VERSION
#define CONST_STRING
static const char * version = "2.xx";
\endverbatim
Note 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 YES
and specify the macro definitions after
the \ref cfg_predefined "PREDEFINED" or
\ref cfg_expand_as_defined "EXPAND_AS_DEFINED" tag.
A typically example where some help from the preprocessor is needed is
when dealing with the language extension from Microsoft: \c __declspec. The same goes
for GNU's \c \__attribute__ extension. Here is an example function.
\verbatim
extern "C" void __declspec(dllexport) ErrorMsg( String aMessage,...);
\endverbatim
When nothing is done, doxygen will be confused and see \c __declspec as
some sort of function. To help doxygen one typically uses the following
preprocessor settings:
\verbatim
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
PREDEFINED = __declspec(x)=
\endverbatim
This will make sure the \c __declspec(dllexport) is removed before doxygen
parses the source code.
Similar settings can be used for removing \c \__attribute__ expressions from the input:
\verbatim
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
PREDEFINED = __attribute__(x)=
\endverbatim
For a more complex example, suppose you have the following obfuscated
code fragment of 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;
};
\endverbatim
without macro expansion doxygen will get confused, but we may not want to
expand the \c 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 configuration file:
\verbatim
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
\endverbatim
we 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;
};
\endverbatim
Note 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 defines
are 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 QListT
class QListT
{
};
\endverbatim
Then the only way to get doxygen interpret this as a class definition
for class \c QList is to define:
\verbatim
PREDEFINED = QListT:=QList
\endverbatim
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:
\verbatim
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)="
\endverbatim
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 \ref cfg_input_filter "INPUT_FILTER" tag.
If you are unsure what the effect of doxygen's preprocessing will be
you can run doxygen as follows:
\verbatim
doxygen -d Preprocessor
\endverbatim
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).
Note preprocessing is not done for all languages. Preprocesing is enabled for files
that use the "C" scanner (with the exception of 'java', 'd' and 'php'), Fortran files
(only in case the extension contains at least one upper case character) and vhdl files.
\htmlonly
Go to the <a href="autolink.html">next</a> section or return to the
<a href="index.html">index</a>.
\endhtmlonly
*/
|
