Make the rules for combining explicitly specified docstring, autodoc one and
the one obtained by translating Doxygen comments implicit in the structure of
the code itself instead of writing complicated conditions checking them.
This results in small changes to the whitespace in the generated Python code
when using autodoc, but this makes it PEP 8-compliant, so it is the right
thing to do anyhow.
Also cache the docstring built from translated Doxygen comments. The existing
code seemed to intend to do it, but didn't, really. This helps with
performance generally speaking (-10% for a relatively big library using a lot
of Doxygen comments) and also makes debugging Doxygen translation code less
painful as it's executed only once instead of twice for each comment.
Finally, avoid putting "r", used for Python raw strings, into docstrings in C
code, it is really not needed there.
It is very useful to be able to click on the parameter types in a function
documentation to go to this parameter description, so always use hyperlink
markup for the parameters of class types, even if not all of them are
necessarily documented -- Sphinx doesn't seem to complain about links to
unknown classes.
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.
This is important to preserve the structure of the lists which appear
correctly in Python output without any additional effort if the indentation is
lost.
It is also makes the behaviour consistent for
/**
*
*
*/
comments and those without the asterisks in the middle lines, as now the
indentation is preserved in both cases while it was only preserved when the
asterisks were present previously.
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.
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.
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.
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).
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.
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.
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.
* Renamed SWIG_Lua_equal to SWIG_Lua_class_equal
* If class has no __eq implemented, then default __eq is provided.
Default __eq compares actual pointers stored inside Lua userdata
* hfalcic-master:
unicode_strings test: manually check values instead of using assert
unicode_strings_runme.py: fix version check
unicode_strings test: check return values
Python unicode_strings test case: restrict to Python > 3.0
Python 3 'surrogateescape' docs: fix div class for Python code
* wkalinin-csymbols-1:
obscure case workaround in std::set wrapper, where ignored type still need to be processed
global unnamed structures ignored
test added for nested unnamed C struct %extend
%extend for nested unnamed C structs
