The autodoc-class fallback in make_autodoc() and the no-docstring
fallback in classHandler() both emitted "::ClassName" under -builtin
where the non-builtin proxy module emits "Proxy of C++ ClassName class."
(or "" when no docstring source is in scope).
Collapse the AUTODOC_CLASS builtin branch so the autodoc-derived text
is identical in both modes, drop the classHandler -builtin block that
seeded feature:python:tp_doc with "::ClassName" when have_docstring is
false, and initialise quoted_tp_doc_str to an empty string rather than
the literal "0" so the tp_doc slot becomes "" instead of inheriting
SwigPyObject's docstring via the MRO lookup that inspect.getdoc() does
on a NULL tp_doc.
Drop the is_python_builtin() gates that this divergence had forced into
autodoc_runme.py, doxygen_autodoc_docstring_runme.py and
doxygen_misc_constructs_runme.py, plus the matching #ifdef
SWIGPYTHON_BUILTIN helpers in doxygen_autodoc_docstring.i and
doxygen_misc_constructs.i. The autodoc.i helper stays - autodoc_runme.py
still needs it to gate the _autodoc.* low-level checks that genuinely
do not exist under -builtin.
The autodoc-driven __init__ checks in autodoc_runme.py also drop their
skip=True guards: 2f8cdc412 already made cdocstring(node, AUTODOC_CTOR)
flow into python:tp_init_doc for autodoc-only constructors as well as
doxygen ones, so the descriptor adapter installs the expected
"__init__(self, ...) -> Foo" string in -builtin too.
Assisted-by: Claude Opus 4.7 (1M context)
Adds two test fixtures to lock down the corner cases of the #3403 fix:
- SlashFileHeaderTestClass exercises the same @file bleed scenario but
with single-line /// comments, which take a different scanner branch
to //!. Without the fix the file header would bleed into the class
description in this style too.
- GroupedMembers exercises @name/@{ member grouping. The discard rule
must NOT fire here: @{ does not terminate the structural block (no
blank line), so each member's own doc comment must still attach. A
regression here would either drop @{ or drop the per-member doc.
Java and Python runmes are kept in step.
Assisted-by: Claude Opus 4.7 <noreply@anthropic.com>
When a header uses consecutive `//!` (or `///`) single-line comments for a
file-level block starting with `@file`, SWIG's comment accumulation loop was
concatenating the file-header content into the following class or function
docstring.
Two bugs conspired:
- Only the `@file` line itself was recognised as structural and skipped;
subsequent lines (`@brief`, `@authors`, ...) are not in `structuralTags[]`
and so were accumulated into `yylval.str`.
- Blank lines between comment groups do not break the accumulation loop
(all `SWIG_TOKEN_ENDLINE` tokens are consumed silently), so the next
declaration's own doc comment was appended to the same string.
Fix: introduce an `in_structural_block` flag. When the first comment in a
group contains a structural command (`@file`, `@page`, ...), set the flag but
continue accumulating content normally. Count newlines in the inner do-while;
when `in_structural_block` is set and two or more consecutive newlines are seen
(a blank line), discard all accumulated content and break, so the following
declaration's doc comment is processed fresh.
Not breaking the loop on a natural exit (no blank line) is deliberate: it
correctly handles the `@name`/`@{` member-grouping pattern, where `@{`
immediately follows `@name` without a blank line and must still be attached to
the next member.
The block-comment style (`/*! @file ... */`) was already handled correctly
because the entire block is one scanner token and `isStructuralDoxygen()`
would see `@file` in it.
Fixes#3403
In addition to the changes in the previous commit, also avoid syntax
errors in the generated Python docstrings by splitting them into several
parts if there are 3 quotes in a row in the input, as it's impossible to
have them inside triple-quoted strings, generally speaking (i.e. if
there are occurrences of both """ and ''' inside the string).
Single-line Doxygen comments ending with a double quote resulted in
syntactically-invalid Python docstrings in the output, so use triple
single quotes as delimiters in this case to avoid it.
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.
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.
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.
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