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.
Enum values are just (integer) constants in Python and so can be used as the
function default values just as well as literal numbers, account for this when
checking whether function parameters can be represented in Python.
Also rename is_primitive_defaultargs() to is_representable_as_pyargs() to
describe better what this function does.
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.
- Examples/Makefile.in rules use SRCDIR as the relative source directory
- ./config.status replicates Examples/ source directory tree in build
directory, and copies each Makefile to build directory, prefixed with
a header which sets SRCDIR to source directory
- Examples/test-suite/.../Makefile.in set SRCDIR from Autoconf-set srcdir
- Examples/test-suite/errors/Makefile.in needs to filter out source
directory from SWIG error messages
- Lua: embedded interpreters are passed location of run-time test
- Python: copy run-time scripts to build directory because of 2to3
conversion; import_packages example copies __init__.py from source
directory; test-suite sets SCRIPTDIR to location of run-time tests
- Javascript: binding.gyp renamed to binding.gyp.in so that $srcdir
can be substituted with SRCDIR; removed './' from require() statements
so that NODE_PATH can be used to point Node.js to build directory
- some of the %.clean rules in the test-suite Makefiles were using a single tab
as an empty rule, dangerous! I've replaced these with the safer '@exit 0'.
It was previously possible to assign "hello" to a variable backed by char[5]
storage in C, and the array contained the correct character data but without
the trailing NUL, which was unexpected in C.
This is not allowed any more, only "helo" can fit into a char[5] now and
anything else fails the type check, just as it already happened for the longer
strings before.
Closes#122
Use the usual C rule for NUL-terminated strings instead of discarding all the
trailing NUL characters.
This was unexpected (as buffers in C code are not necessarily always padded
with NULs to their full length) and also inconsistent among languages as this
was only done for those of them using typemaps/strings.swg but not for C# or
Java, for example, which terminated the string at the first NUL even before
this change.
Notice that this patch couldn't use strlen() or wcslen() with possibly not
NUL-terminated strings, so we had to add [our own equivalents of] strnlen()
and wcsnlen() and use them instead. This required adding yet another parameter
to string typemap macros, so update the example using them accordingly too.
These typemaps are currently defined for C#, Java and Python only and the
tests are provided only for these languages.
Also add a brief description of the new header to the documentation.
Allow using Perl-like \l, \L, \u, \U and \E escape sequences in the
substitution string used with %rename("%(regex:/pattern/subst/)s").
This is useful for e.g. title casing all string after removing some prefix.
Closes#82
This fix makes the handling of type 'float' and 'double' the same. The implementation requires the
C99 isfinite() macro, or otherwise some platform dependent equivalents, to be available.
SF bug #1327
This doesn't have any noticeable effect with the usage of
SWIG_AsWCharPtrAndSize as shipped by SWIG, but could be a problem if a
user is using this function with cptr equal to zero and psize is non-zero
- the length would be incorrectly set due to the call to PyUnicode_GetSize
failing.
