Merge latest master into doxygen branch again.

Update Doxygen-specific Python unit tests to work with the new indentation.

Update one of Doxygen-specific Java tests to still build with the new handling
of srcdir.
Replace DoxygenTranslator debug parameters with a single flags one.

This makes the code more readable and more extensible as more flags are easier
to add in the future than more boolean parameters.

No user-visible changes.
Simplify management of tag handlers in PyDocConverter.

Avoid having to pass dummy empty string arguments, just use default value for
the unused last parameter of handleParagraph().

Also get rid of dozens of "" occurrences in the tag map initialization code,
use a helper function instead.

No real changes.
Show the diff when a Doxygen test fails.

This is much more readable than just dumping the expected output and the
actual result produced by SWIG, especially for longer Doxygen comments.

Remove the bunch of commented out code and also do not save the results
in the file, this is not very useful as it's not even clear which test the
files correspond to and annoying when these files are left over later. If
anybody really uses this functionality, it ought to be optional.
Use Sphinx-compatible docstring format in PyDocConverter.

Use the more or less standard :param:, :type:, :return: and :raises: in the
function/methods descriptions.

Update the output expected from the Python tests accordingly.
Use reST inline markup in PyDocConverter instead of Markdown.

reST is standard Python markup, so use *...*, ``...`` and so on instead of
_..._, '...' etc.

No other changes even though the mapping of some Doxygen tags to markup used
for them seems suspicions (e.g. \var almost certainly should be the same as
\em).
Attach Doxygen comments to enum elements in Python output.

Sphinx is smart enough to use the docstrings following the constant definition
in Python code as its documentation, so doing this is still useful even if
Python itself doesn't support having docstrings for the variables (and this is
why it's impractical to write a unit test for the changes of this commit: we
can't easily extract the generated docstrings).
Hack to ignore custom "noexport" and "iterator" Doxygen commands.

There is no mechanism for registering custom Doxygen keywords (akin to Doxygen
own @alias), so just hard code these two for now.
Implement translation of Doxygen formulae to Sphinx notation.

This allows to automatically have nicely looking formulae in HTML output when
using Sphinx with e.g. sphinx.ext.mathjax extension.
Fix memory leaks in Doxygen to PyDoc parameter types conversion code.

Don't forget to delete the local copy of parameter list and the temporary
string.
No real changes, just rewrite the parameter iteration loop to be more clear.

Also remove unused commented out code.
Use Python-ish, not C++, parameter types in Python documentation.

Using C++ types in documentation for Python users is more harmful than
useless, so use Python types whenever possible and allow defining "doctype"
typemap to customize this for the user-defined types.
Add poor man trailing white space detection to Doxygen Python tests.

Show that there is trailing white space in the output in an ugly but
functional way, as without this it's impossible to determine what is the
actual change at all.
Fix arguments of @param, @return etc translations to Python.

For the parameter documentation to be really taken as such, in its entirety,
by Sphinx, it must be indented relative to the :param: tag. Do this by
appending an extra indent after every line of the output and work around the
unnecessary indent of the last line by removing the trailing whitespace.

This required updating the existing tests and removing the expected but not
present any more whitespace from them, but as trailing whitespace in the
documentation is at best insignificant (and at worst harmful) anyhow, this is
not a big price to pay for simpler translator code.
Use Sphinx-friendly formatting for overloaded functions documentation.

Sphinx doesn't allow sections inside the function documentation and gives tons
of SEVERE warnings for them, so while just emphasizing the "Overload" header
is not ideal, it is better than before because at least the string "Overload"
itself appears in the Sphinx-generated output.