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
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.12"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Doxygen: Troubleshooting</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
</script>
<link href="doxygen_manual.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">Doxygen
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.12 -->
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('trouble.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">Troubleshooting </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="knowproblems"></a>
Known Problems</h1>
<ul>
<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>
<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. </li>
<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>
<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>
<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>
<li>
Redundant braces can confuse doxygen in some cases. For example: <pre class="fragment"> void f (int);
</pre> is properly parsed as a function declaration, but <pre class="fragment"> const int (a);
</pre> is also seen as a function declaration with name <code>int</code>, because only the syntax is analyzed, not the semantics. If the redundant braces can be detected, as in <pre class="fragment"> int *(a[20]);
</pre> then doxygen will remove the braces and correctly parse the result. </li>
<li>
<p class="startli">Not all names in code fragments that are included in the documentation are replaced by links (for instance when using <a class="el" href="config.html#cfg_source_browser">SOURCE_BROWSER</a> = <code>YES</code>) 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.</p>
<p class="endli">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. </p>
</li>
<li>
It is not possible to insert a non-member function f in a class A using the <a class="el" href="commands.html#cmdrelates">\relates</a> or <a class="el" href="commands.html#cmdrelatesalso">\relatesalso</a> command, if class A already has a member with name f and the same argument list. </li>
<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>
<li>
Not all special commands are properly translated to RTF. </li>
<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>
<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. </li>
</ul>
<h1><a class="anchor" id="howtohelp"></a>
How to Help</h1>
<p>The development of doxygen highly depends on your input!</p>
<p>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.</p>
<h1><a class="anchor" id="bug_reports"></a>
How to report a bug</h1>
<p>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>.</p>
<p>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).</p>
<p>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:</p><ul>
<li>The version of doxygen you are using (for instance 1.5.3, use <code>doxygen --version</code> if you are not sure).</li>
<li>The name and version number of your operating system (for instance SuSE Linux 6.4)</li>
<li>It is usually a good idea to send along the configuration 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).</li>
<li>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 <em>after</em> submitting the initial bug description.</li>
</ul>
<p>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.</p>
<p>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 <a href="#" onclick="location.href='mai'+'lto:'+'dim'+'it'+'ri@'+'st'+'ack'+'.n'+'l'; return false;">dimit<span style="display: none;">.nosp@m.</span>ri@s<span style="display: none;">.nosp@m.</span>tack.<span style="display: none;">.nosp@m.</span>nl</a> if you prefer not to send them via the bug tracker or mailing list.</p>
<p>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.</p>
<p>
Go to the <a href="features.html">next</a> section or return to the
<a href="index.html">index</a>.
</p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.12 </li>
</ul>
</div>
</body>
</html>
|
