Simplify and make more efficient building Python docstrings.

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.

Examples/test-suite/python/autodoc_runme.py

@@ -124,19 +124,17 @@ if sys.version_info[0:2] > (2, 4):
   # Python 2.4 does not seem to work
   commentVerifier.check(A.variable_a.__doc__, "A_variable_a_get(self) -> int")
   commentVerifier.check(A.variable_b.__doc__, "A_variable_b_get(A self) -> int")
-  commentVerifier.check(A.variable_c.__doc__, "\n"
+  commentVerifier.check(A.variable_c.__doc__,
   "A_variable_c_get(self) -> int\n"
   "\n"
   "Parameters:\n"
   "    self: A *\n"
-  "\n"
   )
-  commentVerifier.check(A.variable_d.__doc__, "\n"
+  commentVerifier.check(A.variable_d.__doc__,
   "A_variable_d_get(A self) -> int\n"
   "\n"
   "Parameters:\n"
   "    self: A *\n"
-  "\n"
   )
 
 commentVerifier.check(B.__doc__, "Proxy of C++ B class")
@@ -166,9 +164,9 @@ commentVerifier.check(F.__init__.__doc__, "\n"
 commentVerifier.check(B.funk.__doc__, "funk(B self, int c, int d) -> int")
 commentVerifier.check(funk.__doc__, "funk(A e, short arg2, int c, int d) -> int")
 commentVerifier.check(funkdefaults.__doc__, "\n"
-"  funkdefaults(A e, short arg2, int c, int d, double f=2) -> int\n"
-"  funkdefaults(A e, short arg2, int c, int d) -> int\n"
-"  "
+"    funkdefaults(A e, short arg2, int c, int d, double f=2) -> int\n"
+"    funkdefaults(A e, short arg2, int c, int d) -> int\n"
+"    "
 )
 
 commentVerifier.check(func_input.__doc__, "func_input(int * INPUT) -> int")

Examples/test-suite/python/doxygen_basic_notranslate_runme.py

@@ -61,9 +61,7 @@ commentVerifier.check(doxygen_basic_notranslate.function4.__doc__,
     """
 )
 commentVerifier.check(doxygen_basic_notranslate.function5.__doc__,
-    r"""
-    This is a post comment. 
-    """
+    r""" This is a post comment. """
 )
 commentVerifier.check(doxygen_basic_notranslate.function6.__doc__,
     r"""

Examples/test-suite/python/doxygen_basic_translate_runme.py

@@ -59,9 +59,7 @@ commentVerifier.check(doxygen_basic_translate.function4.__doc__,
     """
 )
 commentVerifier.check(doxygen_basic_translate.function5.__doc__,
-    """
-    This is a post comment.
-    """
+    """ This is a post comment."""
 )
 commentVerifier.check(doxygen_basic_translate.function6.__doc__,
     """