trouble.doc 7.23 KB
Newer Older
Dimitri van Heesch's avatar
Dimitri van Heesch committed
1 2
/******************************************************************************
 *
3
 * 
Dimitri van Heesch's avatar
Dimitri van Heesch committed
4
 *
Dimitri van Heesch's avatar
Dimitri van Heesch committed
5
 * Copyright (C) 1997-2014 by Dimitri van Heesch.
Dimitri van Heesch's avatar
Dimitri van Heesch committed
6 7 8 9 10 11 12
 *
 * 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.
 *
Dimitri van Heesch's avatar
Dimitri van Heesch committed
13 14
 * Documents produced by Doxygen are derivative works derived from the
 * input used in their production; they are not affected by this license.
Dimitri van Heesch's avatar
Dimitri van Heesch committed
15 16 17 18
 *
 */
/*! \page trouble Troubleshooting

Dimitri van Heesch's avatar
Dimitri van Heesch committed
19
\section knowproblems Known Problems
Dimitri van Heesch's avatar
Dimitri van Heesch committed
20
<ul>
21 22
<li>If you have problems building doxygen from sources, please 
    read \ref unix_problems "this section" first.
23
<li>Doxygen is <em>not</em> a real compiler, it is only a lexical scanner.
Dimitri van Heesch's avatar
Dimitri van Heesch committed
24
    This means that it can and will not detect errors in your source code.
25 26 27 28 29
<li>Doxygen has a build in preprocessor, but this works slightly different than
    the C preprocessor. Doxygen assumes a header file is properly guarded against
    multiple inclusion, and that each include file is standalone (i.e. it could be placed
    at the top of a source file without causing compiler errors). As long as this is
    true (and this is a good design practice) you should not encounter problems.
30
<li>Since it is impossible to test all possible code fragments, it is
Dimitri van Heesch's avatar
Dimitri van Heesch committed
31 32 33 34 35 36 37 38
    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.
Dimitri van Heesch's avatar
Dimitri van Heesch committed
39
    Inside a HTML link (i.e. \<a&nbsp;href="..."\>...\<a\>) for instance 
Dimitri van Heesch's avatar
Dimitri van Heesch committed
40 41 42 43 44 45 46 47 48 49 50
    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
51
  is also seen as a function declaration with name 
52
  <code>int</code>, because only the syntax is analyzed,
Dimitri van Heesch's avatar
Dimitri van Heesch committed
53 54 55 56 57
  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.
58
<li>Not all names in code fragments that are included in the documentation
59
    are replaced by links (for instance when using \ref cfg_source_browser "SOURCE_BROWSER" = `YES`)
60
    and links to overloaded members may point to the wrong member.
61 62 63
    This also holds for the "Referenced by" list that is generated for
    each function.

64 65
    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
66
    improvements not everything can be properly linked to the corresponding
67 68
    documentation, because of possible ambiguities or lack of
    information about the context in which the code fragment is found.  
Dimitri van Heesch's avatar
Dimitri van Heesch committed
69
<li>It is not possible to insert a non-member function f in a class A 
70 71
    using the \ref cmdrelates "\\relates" or \ref cmdrelatesalso "\\relatesalso" 
    command, if class A already
72
    has a member with name f and the same argument list.
73 74 75 76
<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.
77 78 79
<li>Version 1.8.6 of dot (and maybe earlier versions too) do not 
    generate proper map files, causing the graphs that doxygen generates
    not to be properly clickable.
80 81
<li>PHP only: Doxygen requires that all PHP statements (i.e. code) is 
    wrapped in a functions/methods, otherwise you may run into parse problems.
Dimitri van Heesch's avatar
Dimitri van Heesch committed
82 83 84
</ul>


Dimitri van Heesch's avatar
Dimitri van Heesch committed
85
\section howtohelp How to Help
Dimitri van Heesch's avatar
Dimitri van Heesch committed
86 87 88 89 90 91
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. 

Dimitri van Heesch's avatar
Dimitri van Heesch committed
92
\section bug_reports How to report a bug
Dimitri van Heesch's avatar
Dimitri van Heesch committed
93

94 95 96
Bugs are tracked in GNOME's <a href="http://bugzilla.gnome.org">bugzilla</a> database.
Before submitting a 
<a href="http://bugzilla.gnome.org/enter_bug.cgi?product=doxygen">new bug</a>,
Dimitri van Heesch's avatar
Dimitri van Heesch committed
97 98 99
first <a href="http://bugzilla.gnome.org/query.cgi?format=advanced&product=doxygen">search</a>
through the database if the same bug has already been submitted by others (the doxygen
product will be preselected).
100
If you believe you have found a new bug, 
Dimitri van Heesch's avatar
Dimitri van Heesch committed
101
please <a href="http://bugzilla.gnome.org/enter_bug.cgi?product=doxygen">report it</a>.
102

Dimitri van Heesch's avatar
Dimitri van Heesch committed
103 104 105
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).
Dimitri van Heesch's avatar
Dimitri van Heesch committed
106

Dimitri van Heesch's avatar
Dimitri van Heesch committed
107 108 109 110
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: 
Dimitri van Heesch's avatar
Dimitri van Heesch committed
111
- The version of doxygen you are using (for instance 1.5.3, use 
112
  `doxygen --version` if you are not sure).
113 114
- The name and version number of your operating system (for instance 
  SuSE Linux 6.4)
115
- It is usually a good idea to send along the configuration file as well, 
116
  but please use doxygen with the <code>-s</code> flag while generating it
Dimitri van Heesch's avatar
Dimitri van Heesch committed
117 118 119
  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 
Dimitri van Heesch's avatar
Dimitri van Heesch committed
120
  attach a small example demonstrating the problem you have to the bug report, so I can
Dimitri van Heesch's avatar
Dimitri van Heesch committed
121
  reproduce it on my machine. Please make sure the example is valid
122 123
  source code (could potentially compile) and that the problem is really 
  captured by the example (I often get examples that do not trigger the 
Dimitri van Heesch's avatar
Dimitri van Heesch committed
124
  actual bug!). If you intend to send more than one file please zip or tar
125
  the files together into a single file for easier processing.
Dimitri van Heesch's avatar
Dimitri van Heesch committed
126 127
  Note that when reporting a new bug you'll get a chance to attach a file to it 
  only \e after submitting the initial bug description.
128 129 130

You can (and are encouraged to) add a patch for a bug. If you do so
please use PATCH as a keyword in the bug entry form.
Dimitri van Heesch's avatar
Dimitri van Heesch committed
131

132 133 134 135
If you have ideas 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> 
(subscription required). Patches can also be sent directly to dimitri@stack.nl if 
you prefer not to send them via the bug tracker or mailing list.
136

Dimitri van Heesch's avatar
Dimitri van Heesch committed
137 138 139 140
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.
Dimitri van Heesch's avatar
Dimitri van Heesch committed
141

142
\htmlonly
143 144
Go to the <a href="features.html">next</a> section or return to the
 <a href="index.html">index</a>.
145 146
\endhtmlonly

147

Dimitri van Heesch's avatar
Dimitri van Heesch committed
148 149
*/