--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Orb/Doxygen/doc/trouble.doc Thu Jan 21 17:29:01 2010 +0000
@@ -0,0 +1,142 @@
+/******************************************************************************
+ *
+ *
+ *
+ * Copyright (C) 1997-2008 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>If you have problems building doxygen from sources, please
+ read \ref unix_problems "this section" first.
+<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 is 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)
+ and links to overloaded members may point to the wrong member.
+ 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 everything 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 or \\relatesalso 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.
+<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.
+<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.
+</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>
+
+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>,
+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).
+If you believe you have found a new bug,
+please <a href="http://bugzilla.gnome.org/enter_bug.cgi?product=doxygen">report it</a>.
+
+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.5.3, 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
+ attach a small example demonstrating the problem you have to the bug report, 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 file for easier processing.
+ 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.
+
+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.
+
+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.
+
+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.
+
+\htmlonly
+Return to the <a href="index.html">index</a>.
+\endhtmlonly
+
+*/
+