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
It is unconventional to have a doxygen comment after an enum item. It is
attached to the previous, that is, the enum item to match Doxygen behaviour.
Closes#1609
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.
In particular, do not use com.sun.javadoc deprecated since Java 9 and
finally removed in Java 13, to allow the tests to run under modern JRE.
They don't run under Java 8 and earlier any more, but this shouldn't be
a huge problem nowadays and as SWIG output is independent from the Java
version used, it's enough to test it with modern Java versions.
Note that the tests themselves were changed only in the most minimal
way, to adapt them to the new way of running javadoc (which is now also
integrated into CommentParser itself instead of being duplicated in
every test).
Fix crash if "@return" Doxygen tag was used on a node without any return
type (such as a class, for example). Ignoring it might not be the best
thing to do, but it's definitely better than crashing and it's not
really clear what else could be done anyhow.
Closes#1516.
Found via `codespell -q 3 -L "uint,bae,objext,cmo,goin,struc,ois,upto"`
whitespaces were unintentionally fixed due to my editors settings.
Rebased patch #1327
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.
William S Fulton