|
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 trouble Troubleshooting |
|
18 |
|
19 <h2>Known problems:</h2> |
|
20 <ul> |
|
21 <li>If you have problems building doxygen from sources, please |
|
22 read \ref unix_problems "this section" first. |
|
23 <li>Doxygen is <em>not</em> a real compiler, it is only a lexical scanner. |
|
24 This means that it can and will not detect errors in your source code. |
|
25 <li>Since it is impossible to test all possible code fragments, it is |
|
26 very well possible, that some valid piece of C/C++ code is not handled |
|
27 properly. If you find such a piece, please send it to me, so I can |
|
28 improve doxygen's parsing capabilities. Try to make the piece of code |
|
29 you send as small as possible, to help me narrow down the search. |
|
30 <li>Doxygen does not work properly if there are multiple classes, structs |
|
31 or unions with the same name in your code. It should not crash however, |
|
32 rather it should ignore all of the classes with the same name except one. |
|
33 <li>Some commands do not work inside the arguments of other commands. |
|
34 Inside a HTML link (i.e \<a href="..."\>...\<a\>) for instance |
|
35 other commands (including other HTML commands) do not work! |
|
36 The sectioning commands are an important exception. |
|
37 <li>Redundant braces can confuse doxygen in some cases. |
|
38 For example: |
|
39 \verbatim |
|
40 void f (int); |
|
41 \endverbatim |
|
42 is properly parsed as a function declaration, but |
|
43 \verbatim |
|
44 const int (a); |
|
45 \endverbatim |
|
46 is also seen as a function declaration with name |
|
47 <code>int</code>, because only the syntax is analysed, |
|
48 not the semantics. If the redundant braces can be detected, as in |
|
49 \verbatim |
|
50 int *(a[20]); |
|
51 \endverbatim |
|
52 then doxygen will remove the braces and correctly parse the result. |
|
53 <li>Not all names in code fragments that are included in the documentation |
|
54 are replaced by links (for instance when using \c SOURCE_BROWSER = \c YES) |
|
55 and links to overloaded members may point to the wrong member. |
|
56 This also holds for the "Referenced by" list that is generated for |
|
57 each function. |
|
58 |
|
59 For a part this is because the code parser isn't smart enough at the |
|
60 moment. I'll try to improve this in the future. But even with these |
|
61 improvements not everything can be properly linked to the corresponding |
|
62 documentation, because of possible ambiguities or lack of |
|
63 information about the context in which the code fragment is found. |
|
64 <li>It is not possible to insert a non-member function f in a class A |
|
65 using the \\relates or \\relatesalso command, if class A already |
|
66 has a member with name f and the same argument list. |
|
67 <li>There is only very limited support for member specialization at the |
|
68 moment. It only works if there is a specialized template class as |
|
69 well. |
|
70 <li>Not all special commands are properly translated to RTF. |
|
71 <li>Version 1.8.6 of dot (and maybe earlier versions too) do not |
|
72 generate proper map files, causing the graphs that doxygen generates |
|
73 not to be properly clickable. |
|
74 <li>PHP only: Doxygen requires that all PHP statements (i.e. code) is |
|
75 wrapped in a functions/methods, otherwise you may run into parse problems. |
|
76 </ul> |
|
77 |
|
78 |
|
79 <h2>How to help</h2> |
|
80 The development of Doxygen highly depends on your input! |
|
81 |
|
82 If you are trying Doxygen let me know what you think of it (do you |
|
83 miss certain features?). Even if you decide not to use it, please let me |
|
84 know why. |
|
85 |
|
86 \anchor bug_reports |
|
87 <h2>How to report a bug</h2> |
|
88 |
|
89 Bugs are tracked in GNOME's <a href="http://bugzilla.gnome.org">bugzilla</a> database. |
|
90 Before submitting a |
|
91 <a href="http://bugzilla.gnome.org/enter_bug.cgi?product=doxygen">new bug</a>, |
|
92 first <a href="http://bugzilla.gnome.org/query.cgi?format=advanced&product=doxygen">search</a> |
|
93 through the database if the same bug has already been submitted by others (the doxygen |
|
94 product will be preselected). |
|
95 If you believe you have found a new bug, |
|
96 please <a href="http://bugzilla.gnome.org/enter_bug.cgi?product=doxygen">report it</a>. |
|
97 |
|
98 If you are unsure whether or not something is a bug, please ask help |
|
99 on the <a href="http://sourceforge.net/mail/?group_id=5971">users mailing list</a> |
|
100 first (subscription is required). |
|
101 |
|
102 If you send only a (vague) description of a bug, you are usually not very |
|
103 helpful and it will cost me much more time to figure out what you mean. |
|
104 In the worst-case your bug report may even be completely ignored by me, so |
|
105 always try to include the following information in your bug report: |
|
106 - The version of doxygen you are using (for instance 1.5.3, use |
|
107 <code>doxygen --version</code> if you are not sure). |
|
108 - The name and version number of your operating system (for instance |
|
109 SuSE Linux 6.4) |
|
110 - It is usually a good idea to send along the configuation file as well, |
|
111 but please use doxygen with the <code>-s</code> flag while generating it |
|
112 to keep it small (use <code>doxygen -s -u [configName]</code> to strip |
|
113 the comments from an existing config file). |
|
114 - The easiest (and often the only) way for me to fix bugs is if you can |
|
115 attach a small example demonstrating the problem you have to the bug report, so I can |
|
116 reproduce it on my machine. Please make sure the example is valid |
|
117 source code (could potentially compile) and that the problem is really |
|
118 captured by the example (I often get examples that do not trigger the |
|
119 actual bug!). If you intend to send more than one file please zip or tar |
|
120 the files together into a single file for easier processing. |
|
121 Note that when reporting a new bug you'll get a chance to attach a file to it |
|
122 only \e after submitting the initial bug description. |
|
123 |
|
124 You can (and are encouraged to) add a patch for a bug. If you do so |
|
125 please use PATCH as a keyword in the bug entry form. |
|
126 |
|
127 If you have ideas how to fix existing bugs and limitations please discuss them on |
|
128 the <a href="http://sourceforge.net/mail/?group_id=5971">developers mailing list</a> |
|
129 (subscription required). Patches can also be sent directly to dimitri@stack.nl if |
|
130 you prefer not to send them via the bug tracker or mailing list. |
|
131 |
|
132 For patches please use |
|
133 "diff -uN" or include the files you modified. If you send more than |
|
134 one file please tar or zip everything, so I only have to save and download |
|
135 one file. |
|
136 |
|
137 \htmlonly |
|
138 Return to the <a href="index.html">index</a>. |
|
139 \endhtmlonly |
|
140 |
|
141 */ |
|
142 |