summaryrefslogtreecommitdiffstats
path: root/doc/trouble.doc
blob: b8f742b8a8e5a2697dfe376d94f1c80316f388ab (plain)
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
/******************************************************************************
 *
 * $Id$
 *
 * Copyright (C) 1997-2000 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.
 *
 * All output generated with Doxygen is not covered by this license.
 *
 */
/*! \page trouble Troubleshooting

<h2>Known problems:</h2>
<ul>
<li>Doxygen is <em>not</em> a 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>Using declarations are not yet supported. They are simply ignored.
    Using directives are supported however. 
<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). 
    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.  
</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. 

Furthermore, I would appreciate a mail if you have found
a bug, or if you have ideas (or even better some code or a patch) 
how to fix existing bugs and limitations. 

The easiest way for me to solve bugs is if you can send me a small example
demonstrating the problem you have (make sure the example compiles!). 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. 

My e-mail address: <a href="mailto:dimitri@stack.nl">dimitri@stack.nl</a> 
*/