Processing doxygen @param comments for a parameter whose name did not
appear in the function declaration would cause a segfault due to a
null pointer dereference.
Adding test cases for both variadic function (no specified arguments)
and @param comment that references an argument that is not named in
the function prototype. Both of these cases previously segfaulted.
If the parameter has a default value, add the string ", optional" to
the parameter type description in the translated python comments.
Three examples with default values were already present in the test
cases, so their expected python output has been updated accordingly.
Fix how end of paragraph is identified when parsing \code and
\verbatim blocks that appear within a paragraph and contain an empty
line. Previously this would generate a warning for unexpected end of
doxygen comments, and it could generate a segfault due to
dereferencing an invalid iterator value.
The doxygen_basic_translate.i and doxygen_basic_translate_style2.i
tests have been updated to serve as regression tests for this
behavior. Prior to this fix, inclusion of the empty code block line
in this context produced a segfault.
Sphinx requires an empty line before code and math blocks, whereas
doxygen does not. This update ensures that a blank line is included
before generated code and math blocks in the pydoc output. This is
done by post-processing the docstring line by line to check whether
any newlines need to be added. This way, if the original doxygen
source already includes an empty line before a block, an additional
unnecessary empty line is not added.
Updating the expected test output for doxygen_basic_translate, which
now adds the necessary empty line before the code block. Adding
further test cases to doxygen_translate_all_tags to explicitly verify
that a newline is added in the pydoc output before both code and math
blocks that appear within a paragraph.
Additionally, empty lines previously appearing at the beginning of the
generated docstrings are now removed. This does not alter the
behavior of the tests.
Remove a newline character that was added to the translated comments
prior to the code block. This way the structure of the pydoc output
more closely resembles that of the original doxygen comments.
Updating tests accordingly.
If \code is used as a block command (probably the main use case), an
extra newline was included in the translated Python comments. This is
now removed and doxygen python test case output updated.
Using the standard inspect module instead of accessing __doc__ directly allows
the tests to pass both when using and not using -builtin, as whitespace-only
differences between the docstrings don't matter then because inspect.getdoc()
removes the indentation and the leading and trailing spaces.
This is similar to what had been already done for python_docstring unit test
in fa282b3540.
This is unnecessary and inconsistent with "builtin" case in which the
docstrings are not indented in the generated C++ code, thus making it
impossible to write tests working in both cases.
Most of the changes in this commit simply remove the extra whitespace from the
expected values in the tests.
In addition to translating the comment itself, also document the type of the
object returned. This is consistent with generating not only :param: but also
:type: for the parameters documented using @param.
The most important change is to ensure that the "Overload" headers added by
PyDocConverter code are indented correctly, i.e. using the same indent level
as the comment itself, otherwise Sphinx directives such as :param: were not
parsed correctly.
Also add a vertical separator using reST "|" formatting character to increase
separation between the overloads.
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.
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.
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.
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.
William S Fulton