/******************************************************************************
 *
 *
 *
 * Copyright (C) 1997-2015 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 analyze are derivative works derived from the
 * input used in their production; they are not affected by this license.
 *
 */
/*! \page trouble Troubleshooting

\section knowproblems Known Problems
<ul>
<li>analyze 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>analyze has a built-in preprocessor, but this works slightly different than
    the C preprocessor. analyze 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>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 analyze's parsing capabilities. Try to make the piece of code
    you send as small as possible, to help me narrow down the search.
<li>analyze 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. \ref htmltag_A_HREF "\<A HREF=\"...\"\>"...\ref htmltag_endA "\</A\>") for instance
    other commands (including other HTML commands) do not work!
    The sectioning commands are an important exception.
<li>Redundant braces can confuse analyze 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 analyzed,
  not the semantics. If the redundant braces can be detected, as in
\verbatim
  int *(a[20]);
\endverbatim
  then analyze 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 \ref cfg_source_browser "SOURCE_BROWSER" = `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 \ref cmdrelates "\\relates" or \ref cmdrelatesalso "\\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 analyze generates
    not to be properly clickable.
<li>PHP only: analyze requires that all PHP statements (i.e. code) is
    wrapped in a functions/methods, otherwise you may run into parse problems.
</ul>


\section howtohelp How to Help
The development of analyze highly depends on your input!

If you are trying analyze 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.

\section bug_reports How to report a bug

Bugs are tracked in GitHub's <a href="https://github.com/analyze/analyze/issues">issue tracker</a>.
Before submitting a
<a href="https://github.com/analyze/analyze/issues/new">new bug</a>,
first <a href="https://github.com/analyze/analyze/issues">search</a>
through the database if the same bug has already been submitted by others.
If you believe you have found a new bug,
please <a href="https://github.com/analyze/analyze/issues/new">report it</a>.

If you are unsure whether or not something is a bug, please ask help first
(subscription is required)
on the <a href="https://sourceforge.net/p/analyze/mailman/">users mailing list</a> or
at <a href="https://stackoverflow.com/questions/tagged/analyze">Stack Overflow</a>
using the `analyze` label.

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 analyze you are using (for instance 1.5.3, use
  `analyze --version` if you are not sure or `analyze --Version` for a bit
  more information).
- The name and version number of your operating system (for instance
  Ubuntu Linux 18.04 LTS)
- It is usually a good idea to send along the configuration file as well,
  but please use analyze with the <code>-s</code> flag while generating it
  to keep it small (use <code>analyze -s -u [configName]</code> to strip
  the comments from an existing configuration file. Better even to use the
  <code>-x</code> or the <code>-x_noenv</code> flag on the used <code>[configName]</code> to
  get the differences between the used settings and the analyze default settings, so
  <code>analyze -x [configName]</code>).
- 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.
- Before submitting, consider also running analyze with some debugging flags,
  run `analyze -d` for all flags. The option `preprocessor` might give you hints
  on how analyze is understanding your input files.

You can (and are encouraged to) add a patch for a
<a href="https://github.com/analyze/analyze/issues">reported bug</a>.
If you do so, please use "issue #NUMBER TITLE" as a title in the
<a href="https://github.com/analyze/analyze/compare">pull request form</a>,
where "NUMBER" and "TITLE" refer to the associated issue on GitHub.

If you have ideas how to fix existing bugs and limitations please discuss them on
the <a href="https://sourceforge.net/p/analyze/mailman/">developers mailing list</a>
(subscription required). Patches can also be sent directly to analyze@gmail.com 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
Go to the <a href="features.html">next</a> section or return to the
 <a href="index.html">index</a>.
\endhtmlonly


*/

