This doesn't play well with PEP8 checks which imposes very strict continuation
line indentation rules which need to be _visually_ aligned, i.e. the subsequent
lines must be indented by the position of the opening bracket in the function
declaration line, but the code generating the parameter lists doesn't have
this information and so it's impossible to do it while avoiding either E128 or
E123 ("continuation line {under,over}-indented for visual indent" respectively)
error from pep8.
Moreover, the wrapping code didn't work correctly anyhow as it only took into
account the length of the parameter list itself and not the total line length,
which should include the function name as well.
So just disable wrapping entirely, long lines shouldn't be a problem anyhow in
auto-generated code.
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.
This will allow to reuse them in the code that doesn't have access to a
Language object, such as DoxygenTranslator implementation.
These methods didn't really use any of Language object non-static fields
anyhow, the only one they did use (classtypes or enumtypes, respectively), was
only used for caching and can just as well be made local to the function
itself as long as we use other global variables anyhow.
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.
justifyString() was unused and doesn't seem to be useful as there are no
particular constraints on the line length in Python documentation, so just
preserve whatever is used in the original C++ 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.
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.
Sphinx is smart enough to use the docstrings following the constant definition
in Python code as its documentation, so doing this is still useful even if
Python itself doesn't support having docstrings for the variables (and this is
why it's impractical to write a unit test for the changes of this commit: we
can't easily extract the generated docstrings).
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.
Avoid having to pass dummy empty string arguments, just use default value for
the unused last parameter of handleParagraph().
Also get rid of dozens of "" occurrences in the tag map initialization code,
use a helper function instead.
No real changes.
This makes the code more readable and more extensible as more flags are easier
to add in the future than more boolean parameters.
No user-visible changes.
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.
This fix takes into account the classname while generating overload
handlers.
Example:
If you have two classes:
class A {
public:
void doSomething(int);
void doSomething(double);
};
class B {
public:
void doSomething(int);
void doSomething(double);
};
Before this patch, the overload handlers for A::doSomething and
B::doSomething create conflicting names and function redefinition errors
are caused.
After the patch, the overload handlers are named classname_doSomething
and no longer conflict.
This is might not the best way to implement this, but it
solves a critical problem on large projects, and specifically can affect
operator overloads that are being wrapped.
This is just a simple code refactor, moving and function renaming to
remove the %extend code out of the parser into its own file now
that it isn't just used in the parser.
* 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
Clang seems to be confused by "tm" being the name both of a local variable and
a struct tm from the standard <time.h> header, included indirectly in the
doxygen branch from java.cxx via "swig.h" and <stdlin.h>.
Just removing the unnecessary cast helps to clear the confusion.
No real changes, but avoid having pointer with junk contents, even if it's
unused.
This also avoid the need for checking whether it's used before deleting it.
Use forward declaration instead of including this header in the common header
used by all languages (and not just the two of them that actually use
DoxygenTranslator currently).
This change fixes the crash which happened when parsing the following code:
/// Description of the section.
//@{
...
//@}
As the second Doxygen item didn't have any associated text in this case.
