jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Switch Python Doxygen unit tests to use inspect.getdoc()

Browse source 
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 commit is contained in:
Vadim Zeitlin 2016-12-12 01:20:55 +01:00
commit 148bcab7a0
8 changed files with 171 additions and 244 deletions
Download patch file Download diff file Expand all files Collapse all files

91
Examples/test-suite/python/doxygen_basic_notranslate_runme.py
View file

@ -1,74 +1,65 @@
#!/usr/bin/python #!/usr/bin/python
import doxygen_basic_notranslate import doxygen_basic_notranslate
import inspect
import string import string
import sys import sys
import commentVerifier import commentVerifier
commentVerifier.check(doxygen_basic_notranslate.function.__doc__, commentVerifier.check(inspect.getdoc(doxygen_basic_notranslate.function),
r""" r"""\brief
\brief Brief description.
Brief description.
The comment text The comment text
\author Some author \author Some author
\return Some number \return Some number
\sa function2 \sa function2"""
"""
) )
commentVerifier.check(doxygen_basic_notranslate.function2.__doc__, commentVerifier.check(inspect.getdoc(doxygen_basic_notranslate.function2),
r""" r"""A test of a very very very very very very very very very very very very very very very very
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."""
very very very very very long comment string.
"""
) )
commentVerifier.check(doxygen_basic_notranslate.function3.__doc__, commentVerifier.check(inspect.getdoc(doxygen_basic_notranslate.function3),
r""" *Overload 1:* r"""*Overload 1:*
A test for overloaded functions A test for overloaded functions
This is function \b one This is function \b one
| |
*Overload 2:* *Overload 2:*
A test for overloaded functions A test for overloaded functions
This is function \b two""" This is function \b two"""
) )
commentVerifier.check(doxygen_basic_notranslate.function4.__doc__, commentVerifier.check(inspect.getdoc(doxygen_basic_notranslate.function4),
r""" r"""A test of some mixed tag usage
A test of some mixed tag usage \if CONDITION
\if CONDITION This \a code fragment shows us something \.
This \a code fragment shows us something \. \par Minuses:
\par Minuses: \arg it's senseless
\arg it's senseless \arg it's stupid
\arg it's stupid \arg it's null
\arg it's null
\warning This may not work as expected \warning This may not work as expected
\code \code
int main() { while(true); } int main() { while(true); }
\endcode \endcode
\endif \endif"""
"""
) )
commentVerifier.check(doxygen_basic_notranslate.function5.__doc__, commentVerifier.check(inspect.getdoc(doxygen_basic_notranslate.function5),
r""" This is a post comment. """ r"""This is a post comment. """
) )
commentVerifier.check(doxygen_basic_notranslate.function6.__doc__, commentVerifier.check(inspect.getdoc(doxygen_basic_notranslate.function6),
r""" r"""Test for default args
Test for default args @param a Some parameter, default is 42"""
@param a Some parameter, default is 42
"""
) )
commentVerifier.check(doxygen_basic_notranslate.function7.__doc__, commentVerifier.check(inspect.getdoc(doxygen_basic_notranslate.function7),
r""" r"""Test for a parameter with difficult type
Test for a parameter with difficult type (mostly for python)
(mostly for python) @param a Very strange param"""
@param a Very strange param
"""
) )

46
Examples/test-suite/python/doxygen_basic_translate_runme.py
View file

@ -1,13 +1,13 @@
#!/usr/bin/python #!/usr/bin/python
import doxygen_basic_translate import doxygen_basic_translate
import inspect
import string import string
import sys import sys
import commentVerifier import commentVerifier
commentVerifier.check(doxygen_basic_translate.function.__doc__, commentVerifier.check(inspect.getdoc(doxygen_basic_translate.function),
""" """\
Brief description. Brief description.
The comment text. The comment text.
@ -19,12 +19,12 @@ Author: Some author
See also: function2""" See also: function2"""
) )
commentVerifier.check(doxygen_basic_translate.function2.__doc__, commentVerifier.check(inspect.getdoc(doxygen_basic_translate.function2),
""" """\
A test of a very very very very very very very very very very very very very very very very 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.""" very very very very very long comment string."""
) )
commentVerifier.check(doxygen_basic_translate.function3.__doc__, commentVerifier.check(inspect.getdoc(doxygen_basic_translate.function3),
"""*Overload 1:* """*Overload 1:*
A test for overloaded functions A test for overloaded functions
@ -37,8 +37,8 @@ This is function **one**
A test for overloaded functions A test for overloaded functions
This is function **two**""" This is function **two**"""
) )
commentVerifier.check(doxygen_basic_translate.function4.__doc__, commentVerifier.check(inspect.getdoc(doxygen_basic_translate.function4),
""" """\
A test of some mixed tag usage A test of some mixed tag usage
If: CONDITION { If: CONDITION {
This *code* fragment shows us something . This *code* fragment shows us something .
@ -56,31 +56,31 @@ Warning: This may not work as expected
}""" }"""
) )
commentVerifier.check(doxygen_basic_translate.function5.__doc__, commentVerifier.check(inspect.getdoc(doxygen_basic_translate.function5),
""" This is a post comment.""" """This is a post comment."""
) )
commentVerifier.check(doxygen_basic_translate.function6.__doc__, commentVerifier.check(inspect.getdoc(doxygen_basic_translate.function6),
""" """\
Test for default args Test for default args
:type a: int :type a: int
:param a: Some parameter, default is 42""" :param a: Some parameter, default is 42"""
) )
commentVerifier.check(doxygen_basic_translate.function7.__doc__, commentVerifier.check(inspect.getdoc(doxygen_basic_translate.function7),
""" """\
Test for a parameter with difficult type Test for a parameter with difficult type
(mostly for python) (mostly for python)
:type a: :py:class:`Shape` :type a: :py:class:`Shape`
:param a: Very strange param""" :param a: Very strange param"""
) )
commentVerifier.check(doxygen_basic_translate.Atan2.__doc__, commentVerifier.check(inspect.getdoc(doxygen_basic_translate.Atan2),
""" """\
Multiple parameters test. Multiple parameters test.
:type y: float :type y: float
:param y: Vertical coordinate. :param y: Vertical coordinate.
:type x: float :type x: float
:param x: Horizontal coordinate. :param x: Horizontal coordinate.
:rtype: float :rtype: float
:return: Arc tangent of ``y/x``.""" :return: Arc tangent of ``y/x``."""
) )

13
Examples/test-suite/python/doxygen_ignore_runme.py
View file

@ -1,20 +1,19 @@
#!/usr/bin/python #!/usr/bin/python
import doxygen_ignore import doxygen_ignore
import inspect
import commentVerifier import commentVerifier
commentVerifier.check(doxygen_ignore.func.__doc__, commentVerifier.check(inspect.getdoc(doxygen_ignore.func),
r""" """\
A contrived example of ignoring too many commands in one comment. A contrived example of ignoring too many commands in one comment.
This is specific to **Python**. This is specific to **Python**.
Command ignored, but anything here is still included. Command ignored, but anything here is still included.""")
""")

86
Examples/test-suite/python/doxygen_misc_constructs_runme.py
View file

@ -1,14 +1,14 @@
#!/usr/bin/python #!/usr/bin/python
import doxygen_misc_constructs import doxygen_misc_constructs
import inspect
import string import string
import sys import sys
import commentVerifier import commentVerifier
commentVerifier.check(doxygen_misc_constructs.getAddress.__doc__, commentVerifier.check(inspect.getdoc(doxygen_misc_constructs.getAddress),
r""" r"""Returns address of file line.
Returns address of file line.
:type fileName: int :type fileName: int
:param fileName: name of the file, where the source line is located :param fileName: name of the file, where the source line is located
@ -17,12 +17,10 @@ Returns address of file line.
:type isGetSize: boolean :type isGetSize: boolean
:param isGetSize: if set, for every object location both address and size are returned :param isGetSize: if set, for every object location both address and size are returned
Connection::getId() Connection::getId() """)
""")
commentVerifier.check(doxygen_misc_constructs.CConnectionConfig.__doc__, commentVerifier.check(inspect.getdoc(doxygen_misc_constructs.CConnectionConfig),
r""" r"""This class contains information for connection to winIDEA. Its methods
This class contains information for connection to winIDEA. Its methods
return reference to self, so we can use it like this: return reference to self, so we can use it like this:
CConnectionConfig config = new CConnectionConfig(); CConnectionConfig config = new CConnectionConfig();
@ -34,69 +32,59 @@ used for unspecified parameters.
advancedWinIDEALaunching.py Python example. advancedWinIDEALaunching.py Python example.""")
""")
commentVerifier.check(doxygen_misc_constructs.waitTime.__doc__, commentVerifier.check(inspect.getdoc(doxygen_misc_constructs.waitTime),
r""" r"""Determines how long the ``isystem.connect`` should wait for running
Determines how long the ``isystem.connect`` should wait for running
instances to respond. Only one of ``lfWaitXXX`` flags from IConnect::ELaunchFlags instances to respond. Only one of ``lfWaitXXX`` flags from IConnect::ELaunchFlags
may be specified.""" may be specified."""
) )
commentVerifier.check(doxygen_misc_constructs.getConnection.__doc__, commentVerifier.check(inspect.getdoc(doxygen_misc_constructs.getConnection),
r""" r"""This function returns connection id."""
This function returns connection id."""
) )
commentVerifier.check(doxygen_misc_constructs.getFirstLetter.__doc__, commentVerifier.check(inspect.getdoc(doxygen_misc_constructs.getFirstLetter),
r'' r''
) )
commentVerifier.check(doxygen_misc_constructs.ClassWithNestedEnum.__doc__, commentVerifier.check(inspect.getdoc(doxygen_misc_constructs.ClassWithNestedEnum),
r""" r"""Class description."""
Class description."""
) )
commentVerifier.check(doxygen_misc_constructs.showList.__doc__, commentVerifier.check(inspect.getdoc(doxygen_misc_constructs.showList),
r""" r"""An example of a list in a documentation comment.
An example of a list in a documentation comment.
- The first item of the list. - The first item of the list.
- The second list item, on - The second list item, on
several indented lines, several indented lines,
showing that the indentation showing that the indentation
is preserved. is preserved.
- And the final list item after it. - And the final list item after it.
And this is not a list item any more.""" And this is not a list item any more."""
) )
commentVerifier.check(doxygen_misc_constructs.isNoSpaceValidA.__doc__, commentVerifier.check(inspect.getdoc(doxygen_misc_constructs.isNoSpaceValidA),
r"""This comment without space after '*' is valid in Doxygen. r"""This comment without space after '*' is valid in Doxygen."""
"""
) )
commentVerifier.check(doxygen_misc_constructs.isNoSpaceValidB.__doc__, commentVerifier.check(inspect.getdoc(doxygen_misc_constructs.isNoSpaceValidB),
r""".This comment without space after '*' is valid in Doxygen. r""".This comment without space after '*' is valid in Doxygen."""
"""
) )
commentVerifier.check(doxygen_misc_constructs.isNoSpaceValidC.__doc__, commentVerifier.check(inspect.getdoc(doxygen_misc_constructs.isNoSpaceValidC),
r'' r''
) )
commentVerifier.check(doxygen_misc_constructs.backslashA.__doc__, commentVerifier.check(inspect.getdoc(doxygen_misc_constructs.backslashA),
r""" r"""Backslash following``word`` is a valid doxygen command. Output contains
Backslash following``word`` is a valid doxygen command. Output contains
'followingword' with 'word' in code font.""" 'followingword' with 'word' in code font."""
) )
commentVerifier.check(doxygen_misc_constructs.backslashB.__doc__, commentVerifier.check(inspect.getdoc(doxygen_misc_constructs.backslashB),
r""" r"""Doxy command without trailing space is ignored - nothing appears
Doxy command without trailing space is ignored - nothing appears
on output. Standalone \ and '\' get to output. on output. Standalone \ and '\' get to output.
Standalone @ and '@' get to output. Standalone @ and '@' get to output.
Commands "in quoted \b strings are treated as plain text". Commands "in quoted \b strings are treated as plain text".
@ -110,9 +98,8 @@ Commands for escaped symbols:
$ @ \ & ~ < > # % " . :: @text ::text""" $ @ \ & ~ < > # % " . :: @text ::text"""
) )
commentVerifier.check(doxygen_misc_constructs.backslashC.__doc__, commentVerifier.check(inspect.getdoc(doxygen_misc_constructs.backslashC),
r""" r"""Backslash e at end of *line* froze SWIG
Backslash e at end of *line* froze SWIG
*with* old comment parser. *with* old comment parser.
See also: MyClass::fun(char, See also: MyClass::fun(char,
@ -120,9 +107,8 @@ See also: MyClass::fun(char,
) )
commentVerifier.check(doxygen_misc_constructs.cycle.__doc__, commentVerifier.check(inspect.getdoc(doxygen_misc_constructs.cycle),
r""" r"""The next line contains expression:
The next line contains expression:
['retVal < 10', 'g_counter == 23 && g_mode & 3'] ['retVal < 10', 'g_counter == 23 && g_mode & 3']

58
Examples/test-suite/python/doxygen_parsing_runme.py
View file

@ -1,72 +1,64 @@
#!/usr/bin/python #!/usr/bin/python
import doxygen_parsing import doxygen_parsing
import inspect
import string import string
import os import os
import sys import sys
import commentVerifier import commentVerifier
commentVerifier.check(doxygen_parsing.someFunction.__doc__, commentVerifier.check(inspect.getdoc(doxygen_parsing.someFunction),
r""" "The function comment")
The function comment""") commentVerifier.check(inspect.getdoc(doxygen_parsing.SomeClass),
commentVerifier.check(doxygen_parsing.SomeClass.__doc__, "The class comment")
r""" commentVerifier.check(inspect.getdoc(doxygen_parsing.SomeStruct),
The class comment""") "The struct comment")
commentVerifier.check(doxygen_parsing.SomeStruct.__doc__,
r"""
The struct comment""")
# There doesn't seem to be any way to specify the doc string for __init__ when # There doesn't seem to be any way to specify the doc string for __init__ when
# using "-builtin" (see http://stackoverflow.com/q/11913492/15275), so skip # using "-builtin" (see http://stackoverflow.com/q/11913492/15275), so skip
# this test in this case. # this test in this case.
if str(os.environ.get('SWIG_FEATURES')).find('-builtin') == -1: if str(os.environ.get('SWIG_FEATURES')).find('-builtin') == -1:
commentVerifier.check(doxygen_parsing.SomeAnotherClass.__init__.__doc__, commentVerifier.check(inspect.getdoc(doxygen_parsing.SomeAnotherClass.__init__),
r""" *Overload 1:* r"""*Overload 1:*
First overloaded constructor. First overloaded constructor.
| |
*Overload 2:* *Overload 2:*
Second overloaded constructor.""") Second overloaded constructor.""")
commentVerifier.check(doxygen_parsing.SomeAnotherClass.classMethod.__doc__, commentVerifier.check(inspect.getdoc(doxygen_parsing.SomeAnotherClass.classMethod),
r""" r"""The class method comment.
The class method comment.
SomeAnotherClass#classMethodExtended(int, int) a link text""") SomeAnotherClass#classMethodExtended(int, int) a link text""")
commentVerifier.check(doxygen_parsing.SomeAnotherClass.classMethodExtended.__doc__, commentVerifier.check(inspect.getdoc(doxygen_parsing.SomeAnotherClass.classMethodExtended),
r""" r"""The class method with parameter
The class method with parameter
:type a: int :type a: int
:param a: Parameter a :param a: Parameter a
:type b: int :type b: int
:param b: Parameter b""" :param b: Parameter b"""
) )
commentVerifier.check(doxygen_parsing.SomeAnotherClass.classMethodExtended2.__doc__, commentVerifier.check(inspect.getdoc(doxygen_parsing.SomeAnotherClass.classMethodExtended2),
r""" r"""The class method with parameter
The class method with parameter
:type a: int :type a: int
:param a: Parameter a :param a: Parameter a
:type b: int :type b: int
:param b: Parameter b""" :param b: Parameter b"""
) )
commentVerifier.check(doxygen_parsing.SomeAnotherStruct.structMethod.__doc__, commentVerifier.check(inspect.getdoc(doxygen_parsing.SomeAnotherStruct.structMethod),
r""" r"""The struct method comment""")
The struct method comment""") commentVerifier.check(inspect.getdoc(doxygen_parsing.SomeAnotherStruct.structMethodExtended),
commentVerifier.check(doxygen_parsing.SomeAnotherStruct.structMethodExtended.__doc__, r"""The struct method with parameter
r"""
The struct method with parameter
:type a: int :type a: int
:param a: Parameter a :param a: Parameter a
:type b: int :type b: int
:param b: Parameter b""" :param b: Parameter b"""
) )
commentVerifier.check(doxygen_parsing.SomeAnotherStruct.structMethodExtended2.__doc__, commentVerifier.check(inspect.getdoc(doxygen_parsing.SomeAnotherStruct.structMethodExtended2),
r""" r"""The struct method with parameter
The struct method with parameter
:type a: int :type a: int
:param a: Parameter a :param a: Parameter a

88
Examples/test-suite/python/doxygen_translate_all_tags_runme.py
View file

@ -1,14 +1,14 @@
#!/usr/bin/python #!/usr/bin/python
import doxygen_translate_all_tags import doxygen_translate_all_tags
import inspect
import string import string
import sys import sys
import commentVerifier import commentVerifier
commentVerifier.check(doxygen_translate_all_tags.func01.__doc__, commentVerifier.check(inspect.getdoc(doxygen_translate_all_tags.func01),
r""" r"""*Hello*
*Hello*
@ -39,12 +39,10 @@ Not everything works right now...
.. code-block:: c++ .. code-block:: c++
some test code some test code""")
""")
commentVerifier.check(doxygen_translate_all_tags.func02.__doc__, commentVerifier.check(inspect.getdoc(doxygen_translate_all_tags.func02),
r""" r"""Conditional comment: SOMECONDITION
Conditional comment: SOMECONDITION
Some conditional comment Some conditional comment
End of conditional comment. End of conditional comment.
@ -67,9 +65,8 @@ Deprecated: Now use another function
This is very large This is very large
and detailed description of some thing""") and detailed description of some thing""")
commentVerifier.check(doxygen_translate_all_tags.func03.__doc__, commentVerifier.check(inspect.getdoc(doxygen_translate_all_tags.func03),
r""" r"""Comment for **func03()**.
Comment for **func03()**.
@ -88,10 +85,8 @@ emphazedWord
Example: someFile.txt Example: someFile.txt
Some details on using the example""") Some details on using the example""")
commentVerifier.check(doxygen_translate_all_tags.func04.__doc__, commentVerifier.check(inspect.getdoc(doxygen_translate_all_tags.func04),
r""" r""":raises: SuperError
:raises: SuperError
@ -119,12 +114,10 @@ r"""
This will only appear in hmtl This will only appear in hmtl""")
""")
commentVerifier.check(doxygen_translate_all_tags.func05.__doc__, commentVerifier.check(inspect.getdoc(doxygen_translate_all_tags.func05),
r""" r"""If: ANOTHERCONDITION {
If: ANOTHERCONDITION {
First part of comment First part of comment
If: SECONDCONDITION { If: SECONDCONDITION {
Nested condition text Nested condition text
@ -157,9 +150,8 @@ Image: testImage.bmp("Hello, world!")
Some text Some text
describing invariant.""") describing invariant.""")
commentVerifier.check(doxygen_translate_all_tags.func06.__doc__, commentVerifier.check(inspect.getdoc(doxygen_translate_all_tags.func06),
r""" r"""Comment for **func06()**.
Comment for **func06()**.
@ -181,23 +173,10 @@ someMember Some description follows
This will only appear in man This will only appear in man""")
commentVerifier.check(inspect.getdoc(doxygen_translate_all_tags.func07),
r"""Comment for **func07()**.
""")
commentVerifier.check(doxygen_translate_all_tags.func07.__doc__,
r"""
Comment for **func07()**.
@ -223,21 +202,10 @@ Maybe even multiline
:type a: int :type a: int
:param a: the first param :param a: the first param""")
commentVerifier.check(inspect.getdoc(doxygen_translate_all_tags.func08),
r"""Text after anchor.
""")
commentVerifier.check(doxygen_translate_all_tags.func08.__doc__,
r"""
Text after anchor.
@ -269,13 +237,10 @@ Another remarks section
:return: it :return: it
:rtype: void :rtype: void
:return: may return :return: may return""")
""")
commentVerifier.check(doxygen_translate_all_tags.func09.__doc__, commentVerifier.check(inspect.getdoc(doxygen_translate_all_tags.func09),
r""" r"""This will only appear in RTF
This will only appear in RTF
See also: someOtherMethod See also: someOtherMethod
@ -309,9 +274,8 @@ Since: version 0.0.0.1
:raises: RuntimeError""") :raises: RuntimeError""")
commentVerifier.check(doxygen_translate_all_tags.func10.__doc__, commentVerifier.check(inspect.getdoc(doxygen_translate_all_tags.func10),
r""" r"""TODO: Some very important task
TODO: Some very important task
:type b: float :type b: float
:param b: B is mentioned again... :param b: B is mentioned again...

9
Examples/test-suite/python/doxygen_translate_links_runme.py
View file

@ -1,14 +1,14 @@
#!/usr/bin/python #!/usr/bin/python
import doxygen_translate_links import doxygen_translate_links
import inspect
import string import string
import sys import sys
import commentVerifier import commentVerifier
commentVerifier.check(doxygen_translate_links.function.__doc__, commentVerifier.check(inspect.getdoc(doxygen_translate_links.function),
r""" r"""Testing typenames converting in @ link
Testing typenames converting in @ link
superFunc(int,std::string) superFunc(int,std::string)
Test for std_string member Test for std_string member
@ -37,5 +37,4 @@ some failing params:
See also: superFunc() See also: superFunc()
See also: superFunc() See also: superFunc()
See also: superFunc() See also: superFunc()""")
""")

24
Examples/test-suite/python/doxygen_translate_runme.py
View file

@ -1,14 +1,14 @@
#!/usr/bin/python #!/usr/bin/python
import doxygen_translate import doxygen_translate
import inspect
import string import string
import sys import sys
import commentVerifier import commentVerifier
commentVerifier.check(doxygen_translate.function.__doc__, commentVerifier.check(inspect.getdoc(doxygen_translate.function),
r""" r"""*Hello*
*Hello*
* some list item * some list item
@ -140,9 +140,8 @@ And here goes simple text"""
commentVerifier.check(doxygen_translate.htmlFunction.__doc__, commentVerifier.check(inspect.getdoc(doxygen_translate.htmlFunction),
r""" r"""Test for html tags. See Doxygen doc for list of tags recognized by Doxygen.
Test for html tags. See Doxygen doc for list of tags recognized by Doxygen.
This is link ("http://acme.com/index.html") This is link ("http://acme.com/index.html")
**bold** **bold**
@ -222,13 +221,11 @@ Starts a piece of text displayed in a typewriter font.
*Starts a piece of text displayed in an italic font.* *Starts a piece of text displayed in an italic font.*
<u>underlined \b bold text - doxy commands are ignored inside 'htmlonly' section </u> <u>underlined \b bold text - doxy commands are ignored inside 'htmlonly' section </u>""")
""")
commentVerifier.check(doxygen_translate.htmlTableFunction.__doc__, commentVerifier.check(inspect.getdoc(doxygen_translate.htmlTableFunction),
r""" r"""The meaning of flags:
The meaning of flags:
:type byFlags: int :type byFlags: int
:param byFlags: bits marking required items: :param byFlags: bits marking required items:
@ -243,9 +240,8 @@ The meaning of flags:
``htmlTable...`` functions.""") ``htmlTable...`` functions.""")
commentVerifier.check(doxygen_translate.htmlEntitiesFunction.__doc__, commentVerifier.check(inspect.getdoc(doxygen_translate.htmlEntitiesFunction),
r""" r"""All entities are treated as commands (C) TM (R)
All entities are treated as commands (C) TM (R)
should work also<in text should work also<in text
> >
& &