|
Packit |
1c1d7e |
/******************************************************************************
|
|
Packit |
1c1d7e |
*
|
|
Packit |
1c1d7e |
*
|
|
Packit |
1c1d7e |
*
|
|
Packit |
1c1d7e |
* Copyright (C) 1997-2015 by Dimitri van Heesch.
|
|
Packit |
1c1d7e |
*
|
|
Packit |
1c1d7e |
* Permission to use, copy, modify, and distribute this software and its
|
|
Packit |
1c1d7e |
* documentation under the terms of the GNU General Public License is hereby
|
|
Packit |
1c1d7e |
* granted. No representations are made about the suitability of this software
|
|
Packit |
1c1d7e |
* for any purpose. It is provided "as is" without express or implied warranty.
|
|
Packit |
1c1d7e |
* See the GNU General Public License for more details.
|
|
Packit |
1c1d7e |
*
|
|
Packit |
1c1d7e |
* Documents produced by Doxygen are derivative works derived from the
|
|
Packit |
1c1d7e |
* input used in their production; they are not affected by this license.
|
|
Packit |
1c1d7e |
*
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
/*! \page trouble Troubleshooting
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\section knowproblems Known Problems
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Doxygen is not a real compiler, it is only a lexical scanner.
|
|
Packit |
1c1d7e |
This means that it can and will not detect errors in your source code.
|
|
Packit |
1c1d7e |
Doxygen has a build in preprocessor, but this works slightly different than
|
|
Packit |
1c1d7e |
the C preprocessor. Doxygen assumes a header file is properly guarded against
|
|
Packit |
1c1d7e |
multiple inclusion, and that each include file is standalone (i.e. it could be placed
|
|
Packit |
1c1d7e |
at the top of a source file without causing compiler errors). As long as this is
|
|
Packit |
1c1d7e |
true (and this is a good design practice) you should not encounter problems.
|
|
Packit |
1c1d7e |
Since it is impossible to test all possible code fragments, it is
|
|
Packit |
1c1d7e |
very well possible, that some valid piece of C/C++ code is not handled
|
|
Packit |
1c1d7e |
properly. If you find such a piece, please send it to me, so I can
|
|
Packit |
1c1d7e |
improve doxygen's parsing capabilities. Try to make the piece of code
|
|
Packit |
1c1d7e |
you send as small as possible, to help me narrow down the search.
|
|
Packit |
1c1d7e |
Doxygen does not work properly if there are multiple classes, structs
|
|
Packit |
1c1d7e |
or unions with the same name in your code. It should not crash however,
|
|
Packit |
1c1d7e |
rather it should ignore all of the classes with the same name except one.
|
|
Packit |
1c1d7e |
Some commands do not work inside the arguments of other commands.
|
|
Packit |
1c1d7e |
Inside a HTML link (i.e. \<a href="..."\>...\<a\>) for instance
|
|
Packit |
1c1d7e |
other commands (including other HTML commands) do not work!
|
|
Packit |
1c1d7e |
The sectioning commands are an important exception.
|
|
Packit |
1c1d7e |
Redundant braces can confuse doxygen in some cases.
|
|
Packit |
1c1d7e |
For example:
|
|
Packit |
1c1d7e |
\verbatim
|
|
Packit |
1c1d7e |
void f (int);
|
|
Packit |
1c1d7e |
\endverbatim
|
|
Packit |
1c1d7e |
is properly parsed as a function declaration, but
|
|
Packit |
1c1d7e |
\verbatim
|
|
Packit |
1c1d7e |
const int (a);
|
|
Packit |
1c1d7e |
\endverbatim
|
|
Packit |
1c1d7e |
is also seen as a function declaration with name
|
|
Packit |
1c1d7e |
int , because only the syntax is analyzed,
|
|
Packit |
1c1d7e |
not the semantics. If the redundant braces can be detected, as in
|
|
Packit |
1c1d7e |
\verbatim
|
|
Packit |
1c1d7e |
int *(a[20]);
|
|
Packit |
1c1d7e |
\endverbatim
|
|
Packit |
1c1d7e |
then doxygen will remove the braces and correctly parse the result.
|
|
Packit |
1c1d7e |
Not all names in code fragments that are included in the documentation
|
|
Packit |
1c1d7e |
are replaced by links (for instance when using \ref cfg_source_browser "SOURCE_BROWSER" = `YES`)
|
|
Packit |
1c1d7e |
and links to overloaded members may point to the wrong member.
|
|
Packit |
1c1d7e |
This also holds for the "Referenced by" list that is generated for
|
|
Packit |
1c1d7e |
each function.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
For a part this is because the code parser isn't smart enough at the
|
|
Packit |
1c1d7e |
moment. I'll try to improve this in the future. But even with these
|
|
Packit |
1c1d7e |
improvements not everything can be properly linked to the corresponding
|
|
Packit |
1c1d7e |
documentation, because of possible ambiguities or lack of
|
|
Packit |
1c1d7e |
information about the context in which the code fragment is found.
|
|
Packit |
1c1d7e |
It is not possible to insert a non-member function f in a class A
|
|
Packit |
1c1d7e |
using the \ref cmdrelates "\\relates" or \ref cmdrelatesalso "\\relatesalso"
|
|
Packit |
1c1d7e |
command, if class A already
|
|
Packit |
1c1d7e |
has a member with name f and the same argument list.
|
|
Packit |
1c1d7e |
There is only very limited support for member specialization at the
|
|
Packit |
1c1d7e |
moment. It only works if there is a specialized template class as
|
|
Packit |
1c1d7e |
well.
|
|
Packit |
1c1d7e |
Not all special commands are properly translated to RTF.
|
|
Packit |
1c1d7e |
Version 1.8.6 of dot (and maybe earlier versions too) do not
|
|
Packit |
1c1d7e |
generate proper map files, causing the graphs that doxygen generates
|
|
Packit |
1c1d7e |
not to be properly clickable.
|
|
Packit |
1c1d7e |
PHP only: Doxygen requires that all PHP statements (i.e. code) is
|
|
Packit |
1c1d7e |
wrapped in a functions/methods, otherwise you may run into parse problems.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\section howtohelp How to Help
|
|
Packit |
1c1d7e |
The development of doxygen highly depends on your input!
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
If you are trying doxygen let me know what you think of it (do you
|
|
Packit |
1c1d7e |
miss certain features?). Even if you decide not to use it, please let me
|
|
Packit |
1c1d7e |
know why.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\section bug_reports How to report a bug
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Bugs are tracked in GNOME's bugzilla database.
|
|
Packit |
1c1d7e |
Before submitting a
|
|
Packit |
1c1d7e |
new bug,
|
|
Packit |
1c1d7e |
first search
|
|
Packit |
1c1d7e |
through the database if the same bug has already been submitted by others (the doxygen
|
|
Packit |
1c1d7e |
product will be preselected).
|
|
Packit |
1c1d7e |
If you believe you have found a new bug,
|
|
Packit |
1c1d7e |
please report it.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
If you are unsure whether or not something is a bug, please ask help
|
|
Packit |
1c1d7e |
on the users mailing list
|
|
Packit |
1c1d7e |
first (subscription is required).
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
If you send only a (vague) description of a bug, you are usually not very
|
|
Packit |
1c1d7e |
helpful and it will cost me much more time to figure out what you mean.
|
|
Packit |
1c1d7e |
In the worst-case your bug report may even be completely ignored by me, so
|
|
Packit |
1c1d7e |
always try to include the following information in your bug report:
|
|
Packit |
1c1d7e |
- The version of doxygen you are using (for instance 1.5.3, use
|
|
Packit |
1c1d7e |
`doxygen --version` if you are not sure).
|
|
Packit |
1c1d7e |
- The name and version number of your operating system (for instance
|
|
Packit |
1c1d7e |
SuSE Linux 6.4)
|
|
Packit |
1c1d7e |
- It is usually a good idea to send along the configuration file as well,
|
|
Packit |
1c1d7e |
but please use doxygen with the -s flag while generating it
|
|
Packit |
1c1d7e |
to keep it small (use doxygen -s -u [configName] to strip
|
|
Packit |
1c1d7e |
the comments from an existing config file).
|
|
Packit |
1c1d7e |
- The easiest (and often the only) way for me to fix bugs is if you can
|
|
Packit |
1c1d7e |
attach a small example demonstrating the problem you have to the bug report, so I can
|
|
Packit |
1c1d7e |
reproduce it on my machine. Please make sure the example is valid
|
|
Packit |
1c1d7e |
source code (could potentially compile) and that the problem is really
|
|
Packit |
1c1d7e |
captured by the example (I often get examples that do not trigger the
|
|
Packit |
1c1d7e |
actual bug!). If you intend to send more than one file please zip or tar
|
|
Packit |
1c1d7e |
the files together into a single file for easier processing.
|
|
Packit |
1c1d7e |
Note that when reporting a new bug you'll get a chance to attach a file to it
|
|
Packit |
1c1d7e |
only \e after submitting the initial bug description.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
You can (and are encouraged to) add a patch for a bug. If you do so
|
|
Packit |
1c1d7e |
please use PATCH as a keyword in the bug entry form.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
If you have ideas how to fix existing bugs and limitations please discuss them on
|
|
Packit |
1c1d7e |
the developers mailing list
|
|
Packit |
1c1d7e |
(subscription required). Patches can also be sent directly to dimitri@stack.nl if
|
|
Packit |
1c1d7e |
you prefer not to send them via the bug tracker or mailing list.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
For patches please use
|
|
Packit |
1c1d7e |
"diff -uN" or include the files you modified. If you send more than
|
|
Packit |
1c1d7e |
one file please tar or zip everything, so I only have to save and download
|
|
Packit |
1c1d7e |
one file.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\htmlonly
|
|
Packit |
1c1d7e |
Go to the next section or return to the
|
|
Packit |
1c1d7e |
index.
|
|
Packit |
1c1d7e |
\endhtmlonly
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
|