doc/trouble.doc

   1 /******************************************************************************
   2  *
   3  *
   4  *
   5  * Copyright (C) 1997-2015 by Dimitri van Heesch.
   6  *
   7  * Permission to use, copy, modify, and distribute this software and its
   8  * documentation under the terms of the GNU General Public License is hereby
   9  * granted. No representations are made about the suitability of this software
  10  * for any purpose. It is provided "as is" without express or implied warranty.
  11  * See the GNU General Public License for more details.
  12  *
  13  * Documents produced by Doxygen are derivative works derived from the
  14  * input used in their production; they are not affected by this license.
  15  *
  16  */
  17 /*! \page trouble Troubleshooting
  18
  19 \section knowproblems Known Problems
  20 <ul>
  21 <li>Doxygen is <em>not</em> a real compiler, it is only a lexical scanner.
  22     This means that it can and will not detect errors in your source code.
  23 <li>Doxygen has a build in preprocessor, but this works slightly different than
  24     the C preprocessor. Doxygen assumes a header file is properly guarded against
  25     multiple inclusion, and that each include file is standalone (i.e. it could be placed
  26     at the top of a source file without causing compiler errors). As long as this is
  27     true (and this is a good design practice) you should not encounter problems.
  28 <li>Since it is impossible to test all possible code fragments, it is
  29     very well possible, that some valid piece of C/C++ code is not handled
  30     properly. If you find such a piece, please send it to me, so I can
  31     improve doxygen's parsing capabilities. Try to make the piece of code
  32     you send as small as possible, to help me narrow down the search.
  33 <li>Doxygen does not work properly if there are multiple classes, structs
  34     or unions with the same name in your code. It should not crash however,
  35     rather it should ignore all of the classes with the same name except one.
  36 <li>Some commands do not work inside the arguments of other commands.
  37     Inside a HTML link (i.e. \<a&nbsp;href="..."\>...\<a\>) for instance
  38     other commands (including other HTML commands) do not work!
  39     The sectioning commands are an important exception.
  40 <li>Redundant braces can confuse doxygen in some cases.
  41     For example:
  42 \verbatim
  43   void f (int);
  44 \endverbatim
  45     is properly parsed as a function declaration, but
  46 \verbatim
  47   const int (a);
  48 \endverbatim
  49   is also seen as a function declaration with name
  50   <code>int</code>, because only the syntax is analyzed,
  51   not the semantics. If the redundant braces can be detected, as in
  52 \verbatim
  53   int *(a[20]);
  54 \endverbatim
  55   then doxygen will remove the braces and correctly parse the result.
  56 <li>Not all names in code fragments that are included in the documentation
  57     are replaced by links (for instance when using \ref cfg_source_browser "SOURCE_BROWSER" = `YES`)
  58     and links to overloaded members may point to the wrong member.
  59     This also holds for the "Referenced by" list that is generated for
  60     each function.
  61
  62     For a part this is because the code parser isn't smart enough at the
  63     moment. I'll try to improve this in the future. But even with these
  64     improvements not everything can be properly linked to the corresponding
  65     documentation, because of possible ambiguities or lack of
  66     information about the context in which the code fragment is found.
  67 <li>It is not possible to insert a non-member function f in a class A
  68     using the \ref cmdrelates "\\relates" or \ref cmdrelatesalso "\\relatesalso"
  69     command, if class A already
  70     has a member with name f and the same argument list.
  71 <li>There is only very limited support for member specialization at the
  72     moment. It only works if there is a specialized template class as
  73     well.
  74 <li>Not all special commands are properly translated to RTF.
  75 <li>Version 1.8.6 of dot (and maybe earlier versions too) do not
  76     generate proper map files, causing the graphs that doxygen generates
  77     not to be properly clickable.
  78 <li>PHP only: Doxygen requires that all PHP statements (i.e. code) is
  79     wrapped in a functions/methods, otherwise you may run into parse problems.
  80 </ul>
  81
  82
  83 \section howtohelp How to Help
  84 The development of doxygen highly depends on your input!
  85
  86 If you are trying doxygen let me know what you think of it (do you
  87 miss certain features?). Even if you decide not to use it, please let me
  88 know why.
  89
  90 \section bug_reports How to report a bug
  91
  92 Bugs are tracked in GitHub's <a href="https://github.com/doxygen/doxygen/issues">issue tracker</a>.
  93 Before submitting a
  94 <a href="https://github.com/doxygen/doxygen/issues/new">new bug</a>,
  95 first <a href="https://github.com/doxygen/doxygen/issues">search</a>
  96 through the database if the same bug has already been submitted by others.
  97 If you believe you have found a new bug,
  98 please <a href="https://github.com/doxygen/doxygen/issues/new">report it</a>.
  99
 100 If you are unsure whether or not something is a bug, please ask help
 101 on the <a href="http://sourceforge.net/mail/?group_id=5971">users mailing list</a>
 102 first (subscription is required).
 103
 104 If you send only a (vague) description of a bug, you are usually not very
 105 helpful and it will cost me much more time to figure out what you mean.
 106 In the worst-case your bug report may even be completely ignored by me, so
 107 always try to include the following information in your bug report:
 108 - The version of doxygen you are using (for instance 1.5.3, use
 109   `doxygen --version` if you are not sure).
 110 - The name and version number of your operating system (for instance
 111   Ubuntu Linux 18.04 LTS)
 112 - It is usually a good idea to send along the configuration file as well,
 113   but please use doxygen with the <code>-s</code> flag while generating it
 114   to keep it small (use <code>doxygen -s -u [configName]</code> to strip
 115   the comments from an existing configuration file).
 116 - The easiest (and often the only) way for me to fix bugs is if you can
 117   attach a small example demonstrating the problem you have to the bug report, so I can
 118   reproduce it on my machine. Please make sure the example is valid
 119   source code (could potentially compile) and that the problem is really
 120   captured by the example (I often get examples that do not trigger the
 121   actual bug!). If you intend to send more than one file please zip or tar
 122   the files together into a single file for easier processing.
 123   Note that when reporting a new bug you'll get a chance to attach a file to it
 124   only \e after submitting the initial bug description.
 125
 126 You can (and are encouraged to) add a patch for a bug. If you do so
 127 please use PATCH as a keyword in the bug entry form.
 128
 129 If you have ideas how to fix existing bugs and limitations please discuss them on
 130 the <a href="http://sourceforge.net/mail/?group_id=5971">developers mailing list</a>
 131 (subscription required). Patches can also be sent directly to doxygen@gmail.com if
 132 you prefer not to send them via the bug tracker or mailing list.
 133
 134 For patches please use
 135 "diff -uN" or include the files you modified. If you send more than
 136 one file please tar or zip everything, so I only have to save and download
 137 one file.
 138
 139 \htmlonly
 140 Go to the <a href="features.html">next</a> section or return to the
 141  <a href="index.html">index</a>.
 142 \endhtmlonly
 143
 144
 145 */
 146