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

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.

Examples/test-suite/python/doxygen_basic_notranslate_runme.py

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

Examples/test-suite/python/doxygen_basic_translate_runme.py

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

Examples/test-suite/python/doxygen_ignore_runme.py

@@ -1,20 +1,19 @@
 #!/usr/bin/python
 
 import doxygen_ignore
+import inspect
 import commentVerifier
 
-commentVerifier.check(doxygen_ignore.func.__doc__,
-    r"""
-    A contrived example of ignoring too many commands in one comment.
+commentVerifier.check(inspect.getdoc(doxygen_ignore.func),
+    """\
+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.""")

Examples/test-suite/python/doxygen_misc_constructs_runme.py

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

Examples/test-suite/python/doxygen_parsing_runme.py

@@ -1,72 +1,64 @@
 #!/usr/bin/python
 
 import doxygen_parsing
+import inspect
 import string
 import os
 import sys
 import commentVerifier
 
-commentVerifier.check(doxygen_parsing.someFunction.__doc__,
-    r"""
-The function comment""")
-commentVerifier.check(doxygen_parsing.SomeClass.__doc__,
-    r"""
-The class comment""")
-commentVerifier.check(doxygen_parsing.SomeStruct.__doc__,
-    r"""
-The struct comment""")
+commentVerifier.check(inspect.getdoc(doxygen_parsing.someFunction),
+    "The function comment")
+commentVerifier.check(inspect.getdoc(doxygen_parsing.SomeClass),
+    "The class comment")
+commentVerifier.check(inspect.getdoc(doxygen_parsing.SomeStruct),
+    "The struct comment")
 
 # 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
 # this test in this case.
 if str(os.environ.get('SWIG_FEATURES')).find('-builtin') == -1:
-    commentVerifier.check(doxygen_parsing.SomeAnotherClass.__init__.__doc__,
-    r""" *Overload 1:*
- First overloaded constructor.
+    commentVerifier.check(inspect.getdoc(doxygen_parsing.SomeAnotherClass.__init__),
+    r"""*Overload 1:*
+First overloaded constructor.
 
- |
+|
 
- *Overload 2:*
- Second overloaded constructor.""")
+*Overload 2:*
+Second overloaded constructor.""")
 
-commentVerifier.check(doxygen_parsing.SomeAnotherClass.classMethod.__doc__,
-    r"""
-The class method comment.
+commentVerifier.check(inspect.getdoc(doxygen_parsing.SomeAnotherClass.classMethod),
+    r"""The class method comment.
 
 SomeAnotherClass#classMethodExtended(int, int) a link text""")
-commentVerifier.check(doxygen_parsing.SomeAnotherClass.classMethodExtended.__doc__,
-    r"""
-The class method with parameter
+commentVerifier.check(inspect.getdoc(doxygen_parsing.SomeAnotherClass.classMethodExtended),
+    r"""The class method with parameter
 
 :type a: int
 :param a: Parameter a
 :type b: int
 :param b: Parameter b"""
 )
-commentVerifier.check(doxygen_parsing.SomeAnotherClass.classMethodExtended2.__doc__,
-    r"""
-The class method with parameter
+commentVerifier.check(inspect.getdoc(doxygen_parsing.SomeAnotherClass.classMethodExtended2),
+    r"""The class method with parameter
 
 :type a: int
 :param a: Parameter a
 :type b: int
 :param b: Parameter b"""
 )
-commentVerifier.check(doxygen_parsing.SomeAnotherStruct.structMethod.__doc__,
-    r"""
-The struct method comment""")
-commentVerifier.check(doxygen_parsing.SomeAnotherStruct.structMethodExtended.__doc__,
-    r"""
-The struct method with parameter
+commentVerifier.check(inspect.getdoc(doxygen_parsing.SomeAnotherStruct.structMethod),
+    r"""The struct method comment""")
+commentVerifier.check(inspect.getdoc(doxygen_parsing.SomeAnotherStruct.structMethodExtended),
+    r"""The struct method with parameter
 
 :type a: int
 :param a: Parameter a
 :type b: int
 :param b: Parameter b"""
 )
-commentVerifier.check(doxygen_parsing.SomeAnotherStruct.structMethodExtended2.__doc__,
-    r"""
-The struct method with parameter
+commentVerifier.check(inspect.getdoc(doxygen_parsing.SomeAnotherStruct.structMethodExtended2),
+    r"""The struct method with parameter
 
 :type a: int
 :param a: Parameter a

Examples/test-suite/python/doxygen_translate_all_tags_runme.py

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

Examples/test-suite/python/doxygen_translate_links_runme.py

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

Examples/test-suite/python/doxygen_translate_runme.py

@@ -1,14 +1,14 @@
 #!/usr/bin/python
 
 import doxygen_translate
+import inspect
 import string
 import sys
 import commentVerifier
 
 
-commentVerifier.check(doxygen_translate.function.__doc__,
-r"""
-*Hello*
+commentVerifier.check(inspect.getdoc(doxygen_translate.function),
+r"""*Hello*
 
 * some list item
 
@@ -140,9 +140,8 @@ And here goes simple text"""
 
 
 
-commentVerifier.check(doxygen_translate.htmlFunction.__doc__,
-r"""
-Test for html tags. See Doxygen doc for list of tags recognized by Doxygen.
+commentVerifier.check(inspect.getdoc(doxygen_translate.htmlFunction),
+r"""Test for html tags. See Doxygen doc for list of tags recognized by Doxygen.
 
 This is link ("http://acme.com/index.html")
 **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.*
 
 
-<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__,
-r"""
-The meaning of flags:
+commentVerifier.check(inspect.getdoc(doxygen_translate.htmlTableFunction),
+r"""The meaning of flags:
 
 :type byFlags: int
 :param byFlags: bits marking required items:
@@ -243,9 +240,8 @@ The meaning of flags:
       ``htmlTable...`` functions.""")
 
 
-commentVerifier.check(doxygen_translate.htmlEntitiesFunction.__doc__,
-r"""
-All entities are treated as commands (C)  TM (R)
+commentVerifier.check(inspect.getdoc(doxygen_translate.htmlEntitiesFunction),
+r"""All entities are treated as commands (C)  TM (R)
 should work also<in text
 >
 &