|
1 /****************************************************************************** |
|
2 * |
|
3 * |
|
4 * |
|
5 * Copyright (C) 1997-2008 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 faq Frequently Asked Questions |
|
18 |
|
19 <ol> |
|
20 <li><b>How to get information on the index page in HTML?</b> |
|
21 <p> |
|
22 You should use the \\mainpage command inside a comment block like this: |
|
23 \verbatim |
|
24 /*! \mainpage My Personal Index Page |
|
25 * |
|
26 * \section intro_sec Introduction |
|
27 * |
|
28 * This is the introduction. |
|
29 * |
|
30 * \section install_sec Installation |
|
31 * |
|
32 * \subsection step1 Step 1: Opening the box |
|
33 * |
|
34 * etc... |
|
35 */ |
|
36 \endverbatim |
|
37 |
|
38 <li><b>Help, some/all of the members of my class / file / namespace |
|
39 are not documented?</b> |
|
40 |
|
41 Check the following: |
|
42 <ol> |
|
43 <li>Is your class / file / namespace documented? If not, it will not |
|
44 be extracted from the sources unless \c EXTRACT_ALL is set to \c YES |
|
45 in the config file. |
|
46 <li>Are the members private? If so, you must set \c EXTRACT_PRIVATE to \c YES |
|
47 to make them appear in the documentation. |
|
48 <li>Is there a function macro in your class that does not end with a |
|
49 semicolon (e.g. MY_MACRO())? If so then you have to instruct |
|
50 doxygen's preprocessor to remove it. |
|
51 |
|
52 This typically boils down to the following settings in the config file: |
|
53 |
|
54 \verbatim |
|
55 ENABLE_PREPROCESSING = YES |
|
56 MACRO_EXPANSION = YES |
|
57 EXPAND_ONLY_PREDEF = YES |
|
58 PREDEFINED = MY_MACRO()= |
|
59 \endverbatim |
|
60 |
|
61 Please read the \ref preprocessing "preprocessing" section of the |
|
62 manual for more information. |
|
63 </ol> |
|
64 |
|
65 <li><b>When I set EXTRACT_ALL to NO none of my functions are shown in the |
|
66 documentation.</b> |
|
67 |
|
68 In order for global functions, variables, enums, typedefs, and defines |
|
69 to be documented you should document the file in which these commands are |
|
70 located using a comment block containing a \\file (or \@file) |
|
71 command. |
|
72 |
|
73 Alternatively, you can put all members in a group (or module) |
|
74 using the \\ingroup command and then document the group using a comment |
|
75 block containing the \\defgroup command. |
|
76 |
|
77 For member functions or functions that are part of a namespace you should |
|
78 document either the class or namespace. |
|
79 |
|
80 <li><b>How can I make doxygen ignore some code fragment?</b> |
|
81 |
|
82 The new and easiest way is to add one comment block |
|
83 with a \ref cmdcond "\\cond" command at the start and one comment block |
|
84 with a \ref cmdendcond "\\endcond" command at the end of the piece of |
|
85 code that should be ignored. This should be within the same file of course. |
|
86 |
|
87 But you can also use Doxygen's preprocessor for this: |
|
88 If you put |
|
89 \verbatim |
|
90 #ifndef DOXYGEN_SHOULD_SKIP_THIS |
|
91 |
|
92 /* code that must be skipped by Doxygen */ |
|
93 |
|
94 #endif /* DOXYGEN_SHOULD_SKIP_THIS */ |
|
95 \endverbatim |
|
96 around the blocks that should be hidden and put: |
|
97 \verbatim |
|
98 PREDEFINED = DOXYGEN_SHOULD_SKIP_THIS |
|
99 \endverbatim |
|
100 in the config file then all blocks should be skipped by Doxygen as long |
|
101 as <code>PREPROCESSING = YES</code>. |
|
102 |
|
103 <li><b>How can I change what is after the <code>\#include</code> in the class documentation?</b> |
|
104 |
|
105 In most cases you can use STRIP_FROM_INC_PATH to strip a user defined |
|
106 part of a path. |
|
107 |
|
108 You can also document your class as follows |
|
109 |
|
110 \verbatim |
|
111 /*! \class MyClassName include.h path/include.h |
|
112 * |
|
113 * Docs for MyClassName |
|
114 */ |
|
115 \endverbatim |
|
116 |
|
117 To make doxygen put <br><br> |
|
118 <code> |
|
119 \#include \<path/include.h\> |
|
120 </code> |
|
121 |
|
122 in the documentation of the class MyClassName regardless of the name of the actual |
|
123 header file in which the definition of MyClassName is contained. |
|
124 |
|
125 If you want doxygen to show that the include file should be included using |
|
126 quotes instead of angle brackets you should type: |
|
127 \verbatim |
|
128 /*! \class MyClassName myhdr.h "path/myhdr.h" |
|
129 * |
|
130 * Docs for MyClassName |
|
131 */ |
|
132 \endverbatim |
|
133 |
|
134 <li><b>How can I use tag files in combination with compressed HTML?</b> |
|
135 |
|
136 If you want to refer from one compressed HTML file |
|
137 \c a.chm to another compressed HTML file |
|
138 called \c b.chm, the |
|
139 link in \c a.chm must have the following format: |
|
140 \verbatim |
|
141 <a href="b.chm::/file.html"> |
|
142 \endverbatim |
|
143 Unfortunately this only works if both compressed HTML files are in the same |
|
144 directory. |
|
145 |
|
146 As a result you must rename the generated \c index.chm files for all projects |
|
147 into something unique and put all <code>.chm</code> files in one directory. |
|
148 |
|
149 Suppose you have a project \e a referring to a project \e b using tag file |
|
150 \c b.tag, then you could rename the \c index.chm for project \e a into |
|
151 \c a.chm and the \c index.chm for project \e b into \c b.chm. In the |
|
152 configuration file for project \e a you write: |
|
153 \verbatim |
|
154 TAGFILES = b.tag=b.chm:: |
|
155 \endverbatim |
|
156 or you can use \c installdox to set the links as follows: |
|
157 \verbatim |
|
158 installdox -lb.tag@b.chm:: |
|
159 \endverbatim |
|
160 |
|
161 <li><b>I don't like the quick index that is put above each HTML page, what do I do?</b> |
|
162 |
|
163 You can disable the index by setting DISABLE_INDEX to YES. Then you can |
|
164 put in your own header file by writing your own header and feed that to |
|
165 HTML_HEADER. |
|
166 |
|
167 <li><b>The overall HTML output looks different, while I only wanted to |
|
168 use my own html header file</b> |
|
169 |
|
170 You probably forgot to include the stylesheet <code>doxygen.css</code> that |
|
171 doxygen generates. You can include this by putting |
|
172 \verbatim |
|
173 <LINK HREF="doxygen.css" REL="stylesheet" TYPE="text/css"> |
|
174 \endverbatim |
|
175 in the HEAD section of the HTML page. |
|
176 |
|
177 <li><b>Why does doxygen use Qt?</b> |
|
178 |
|
179 The most important reason is to have a platform abstraction for most |
|
180 Unices and Windows by means of the QFile, QFileInfo, QDir, QDate, |
|
181 QTime and QIODevice classes. |
|
182 Another reason is for the nice and bug free utility classes, like QList, |
|
183 QDict, QString, QArray, QTextStream, QRegExp, QXML etc. |
|
184 |
|
185 The GUI front-end doxywizard uses Qt for... well... the GUI! |
|
186 |
|
187 <li><b>How can I exclude all test directories from my directory tree?</b> |
|
188 |
|
189 Simply put an exclude pattern like this in the configuration file: |
|
190 |
|
191 \verbatim |
|
192 EXCLUDE_PATTERNS = */test/* |
|
193 \endverbatim |
|
194 |
|
195 <li><b>Doxygen automatically generates a link to the |
|
196 class MyClass somewhere in the running text. |
|
197 How do I prevent that at a certain place?</b> |
|
198 |
|
199 Put a \% in front of the class name. Like this: \%MyClass. Doxygen will then |
|
200 remove the % and keep the word unlinked. |
|
201 |
|
202 <li><b>My favourite programming language is X. Can I still use doxygen?</b> |
|
203 |
|
204 No, not as such; doxygen needs to understand the structure of what it reads. |
|
205 If you don't mind spending some time on it, there are several options: |
|
206 - If the grammar of X is close to C or C++, then it is probably not too hard to |
|
207 tweak src/scanner.l a bit so the language is supported. This is done |
|
208 for all other languages directly supported by doxygen |
|
209 (i.e. Java, IDL, C#, PHP). |
|
210 - If the grammar of X is somewhat different than you can write an input |
|
211 filter that translates X into something similar enough to C/C++ for |
|
212 doxygen to understand (this approach is taken for VB, Object Pascal, and |
|
213 Javascript, see http://www.stack.nl/~dimitri/doxygen/download.html#helpers). |
|
214 - If the grammar is completely different one could write a parser for X and |
|
215 write a backend that produces a similar syntax tree as is done by |
|
216 src/scanner.l (and also by src/tagreader.cpp while reading tag files). |
|
217 |
|
218 <li><b>Help! I get the cryptic message |
|
219 "input buffer overflow, can't enlarge buffer because scanner uses REJECT"</b> |
|
220 |
|
221 This error happens when doxygen's lexical scanner has a rule that matches |
|
222 more than 256K of input characters in one go. I've seen this happening |
|
223 on a very large generated file (\>256K lines), where the built-in preprocessor |
|
224 converted it into an empty file (with \>256K of newlines). Another case |
|
225 where this might happen is if you have lines in your code with more than |
|
226 256K characters. |
|
227 |
|
228 If you have run into such a case and want me to fix it, you |
|
229 should send me a code fragment that triggers the message. To work around |
|
230 the problem, put some line-breaks into your file, split it up into smaller |
|
231 parts, or exclude it from the input using EXCLUDE. |
|
232 |
|
233 <li><b>When running make in the latex dir I get "TeX capacity exceeded". Now what?</b> |
|
234 |
|
235 You can edit the texmf.cfg file to increase the default values of the |
|
236 various buffers and then run "texconfig init". |
|
237 |
|
238 <li><b>Why are dependencies via STL classes not shown in the dot graphs?</b> |
|
239 |
|
240 Doxygen is unware of the STL classes, unless the option BUILTIN_STL_SUPPORT is |
|
241 turned on. |
|
242 |
|
243 <li><b>I have problems getting the search engine to work with PHP5 and/or windows</b> |
|
244 |
|
245 Please read <a href="searchengine.html">this</a> for hints on where to look. |
|
246 |
|
247 <li><b>Can I configure doxygen from the command line?</b> |
|
248 |
|
249 Not via command line options, but doxygen can read from <code>stdin</code>, |
|
250 so you can pipe things through it. Here's an example how to override an option |
|
251 in a configuration file from the command line (assuming a unix environment): |
|
252 |
|
253 \verbatim |
|
254 ( cat Doxyfile ; echo "PROJECT_NUMBER=1.0" ) | doxygen - |
|
255 \endverbatim |
|
256 |
|
257 If multiple options with the same name are specified then doxygen will use |
|
258 the last one. To append to an existing option you can use the += operator. |
|
259 |
|
260 <li><b>How did doxygen get its name?</b> |
|
261 |
|
262 Doxygen got its name from playing with the words |
|
263 documentation and generator. |
|
264 |
|
265 \verbatim |
|
266 documentation -> docs -> dox |
|
267 generator -> gen |
|
268 \endverbatim |
|
269 |
|
270 At the time I was looking into lex and yacc, where a lot of things start with |
|
271 "yy", so the "y" slipped in and made things pronounceable |
|
272 (the proper pronouncement is Docs-ee-gen, so with a long "e"). |
|
273 |
|
274 <li><b>What was the reason to develop doxygen?</b> |
|
275 |
|
276 I once wrote a GUI widget based on the Qt library (it is still available at |
|
277 http://qdbttabular.sourceforge.net/ and maintained by Sven Meyer). |
|
278 Qt had nicely generated documentation (using an internal tool which |
|
279 they didn't want to release) and I wrote similar docs by hand. |
|
280 This was a nightmare to maintain, so I wanted a similar tool. I looked at |
|
281 Doc++ but that just wasn't good enough (it didn't support signals and |
|
282 slots and did not have the Qt look and feel I had grown to like), |
|
283 so I started to write my own tool... |
|
284 |
|
285 </ol> |
|
286 |
|
287 \htmlonly |
|
288 Go to the <a href="trouble.html">next</a> section or return to the |
|
289 <a href="index.html">index</a>. |
|
290 \endhtmlonly |
|
291 |
|
292 */ |
|
293 |