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
|
/******************************************************************************
*
*
*
* Copyright (C) 1997-2002 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 trouble Troubleshooting
<h2>Known problems:</h2>
<ul>
<li>Doxygen is <em>not</em> a real compiler, it is only a lexical scanner.
This means that it can and will not detect errors in your source code.
<li>Since it impossible to test all possible code fragments, it is
very well possible, that some valid piece of C/C++ code is not handled
properly. If you find such a piece, please send it to me, so I can
improve doxygen's parsing capabilities. Try to make the piece of code
you send as small as possible, to help me narrow down the search.
<li>Doxygen does not work properly if there are multiple classes, structs
or unions with the same name in your code. It should not crash however,
rather it should ignore all of the classes with the same name except one.
<li>Some commands do not work inside the arguments of other commands.
Inside a HTML link (i.e \<a href="..."\>...\<a\>) for instance
other commands (including other HTML commands) do not work!
The sectioning commands are an important exception.
<li>Redundant braces can confuse doxygen in some cases.
For example:
\verbatim
void f (int);
\endverbatim
is properly parsed as a function declaration, but
\verbatim
const int (a);
\endverbatim
is also seen as a function declaration with name
<code>int</code>, because only the syntax is analysed,
not the semantics. If the redundant braces can be detected, as in
\verbatim
int *(a[20]);
\endverbatim
then doxygen will remove the braces and correctly parse the result.
<li>Not all names in code fragments that are included in the documentation
are replaced by links (for instance when using \c SOURCE_BROWSER = \c YES).
This also holds for the "Referenced by" list that is generated for
each function.
For a part this is because the code parser isn't smart enough at the
moment. I'll try to improve this in the future. But even with these
improvements not everthing can be properly linked to the corresponding
documentation, because of possible ambiguities or lack of
information about the context in which the code fragment is found.
<li>It is not possible to insert a non-member function f in a class A
using the \\relates command, if class A already has a member with name f
and the same argument list.
<li>There is only very limited support for member specialization at the
moment. It only works if there is a specialized template class as
well.
<li>Not all special commands are properly translated to RTF.
</ul>
<h2>How to help</h2>
The development of Doxygen highly depends on your input!
If you are trying Doxygen let me know what you think of it (do you
miss certain features?). Even if you decide not to use it, please let me
know why.
\anchor bug_reports
<h2>How to report a bug</h2>
If you find a bug please send an e-mail to: dimitri@stack.nl.
If you are unsure whether or not something is a bug, please ask help
on the <a href="http://sourceforge.net/mail/?group_id=5971">users mailing list</a>
first (subscription is required).
If you send only a (vague) description of a bug, you are usually not very
helpful and it will cost me much more time to figure out what you mean.
In the worst-case your bug report may even be completely ignored by me, so
always try to include the following information in your bug report:
- The version of doxygen you are using (for instance 1.2.4, use
<code>doxygen --version</code> if you are not sure).
- The name and version number of your operating system (for instance
SuSE Linux 6.4)
- It is usually a good idea to send along the configuation file as well,
but please use doxygen with the <code>-s</code> flag while generating it
to keep it small (use <code>doxygen -s -u [configName]</code> to strip
the comments from an existing config file).
- The easiest (and often the only) way for me to fix bugs is if you can
send me a small example demonstrating the problem you have, so I can
reproduce it on my machine. Please make sure the example is valid
source code (could potentially compile) and that the problem is really
captured by the example (I often get examples that do not trigger the
actual bug!). If you intend to send more than one file please zip or tar
the files together into a single attachment for easier processing.
If you have ideas (or even better some code or a patch)
how to fix existing bugs and limitations please discuss them on
the <a href="http://sourceforge.net/mail/?group_id=5971">developers mailing list</a>.
Patches can also send directly to dimitri@stack.nl.
For patches please use
"diff -uN" or include the files you modified. If you send more than
one file please tar or zip everything, so I only have to save and download
one file.
Note that you can also post bug reports via the bug tracker at
sourceforge, but I do not really like this because of its web
interface, which I find rather clumpsy to use.
*/
|
