16548cced0
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.
90 lines
1.9 KiB
Python
90 lines
1.9 KiB
Python
#!/usr/bin/python
|
|
|
|
import doxygen_basic_translate
|
|
import string
|
|
import sys
|
|
import commentVerifier
|
|
|
|
commentVerifier.check(doxygen_basic_translate.function.__doc__,
|
|
"""
|
|
Brief description.
|
|
|
|
The comment text.
|
|
|
|
Author: Some author
|
|
|
|
:return: Some number
|
|
|
|
See also: function2
|
|
"""
|
|
)
|
|
commentVerifier.check(doxygen_basic_translate.function2.__doc__,
|
|
"""
|
|
A test of a very very very very very very very very very very very very very very very very
|
|
very very very very very long comment string.
|
|
"""
|
|
)
|
|
commentVerifier.check(doxygen_basic_translate.function3.__doc__,
|
|
"""
|
|
*Overload 1:*
|
|
|
|
A test for overloaded functions
|
|
This is function **one**
|
|
|
|
*Overload 2:*
|
|
|
|
A test for overloaded functions
|
|
This is function **two**
|
|
|
|
"""
|
|
)
|
|
commentVerifier.check(doxygen_basic_translate.function4.__doc__,
|
|
"""
|
|
A test of some mixed tag usage
|
|
If: CONDITION {
|
|
This *code* fragment shows us something .
|
|
Title: Minuses:
|
|
* it\'s senseless
|
|
* it\'s stupid
|
|
* it\'s null
|
|
|
|
Warning: This may not work as expected
|
|
|
|
.. code-block:: c++
|
|
|
|
|
|
int main() { while(true); }
|
|
|
|
}
|
|
"""
|
|
)
|
|
commentVerifier.check(doxygen_basic_translate.function5.__doc__,
|
|
""" This is a post comment."""
|
|
)
|
|
commentVerifier.check(doxygen_basic_translate.function6.__doc__,
|
|
"""
|
|
Test for default args
|
|
:type a: int
|
|
:param a: Some parameter, default is 42
|
|
"""
|
|
)
|
|
commentVerifier.check(doxygen_basic_translate.function7.__doc__,
|
|
"""
|
|
Test for a parameter with difficult type
|
|
(mostly for python)
|
|
:type a: :py:class:`Shape`
|
|
:param a: Very strange param
|
|
"""
|
|
)
|
|
|
|
commentVerifier.check(doxygen_basic_translate.Atan2.__doc__,
|
|
"""
|
|
Multiple parameters test.
|
|
|
|
:type y: float
|
|
:param y: Vertical coordinate.
|
|
:type x: float
|
|
:param x: Horizontal coordinate.
|
|
:return: Arc tangent of ``y/x``.
|
|
"""
|
|
)
|