Use Sphinx-compatible docstring format in PyDocConverter.

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.

Examples/test-suite/python/doxygen_basic_translate_runme.py

@@ -13,7 +13,7 @@ commentVerifier.check(doxygen_basic_translate.function.__doc__,
 
     Author: Some author
 
-    Return: Some number
+    :return: Some number
 
     See also: function2
     """
@@ -65,15 +65,15 @@ commentVerifier.check(doxygen_basic_translate.function5.__doc__,
 commentVerifier.check(doxygen_basic_translate.function6.__doc__,
     """
     Test for default args
-    Arguments:
-      a (int) -- Some parameter, default is 42
+    :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)
-    Arguments:
-      a (Shape::superType *[10]) -- Very strange param
+    :type a: Shape::superType *[10]
+    :param a: Very strange param
     """
 )

Examples/test-suite/python/doxygen_misc_constructs_runme.py

@@ -10,10 +10,12 @@ commentVerifier.check(doxygen_misc_constructs.getAddress.__doc__,
     r"""
     Returns address of file line.
 
-    Arguments:
-      fileName (int &) -- name of the file, where the source line is located
-      line (int) -- line number
-      isGetSize (bool) -- if set, for every object location both address and size are returned
+    :type fileName: int &
+    :param fileName: name of the file, where the source line is located
+    :type line: int
+    :param line: line number
+    :type isGetSize: bool
+    :param isGetSize: if set, for every object location both address and size are returned
 
     Connection::getId() 
 
@@ -127,8 +129,8 @@ commentVerifier.check(doxygen_misc_constructs.cycle.__doc__,
     Similar __for__: double colon.
 
     Spaces at the start of line should be taken into account:
-    Arguments:
-      id (int) -- used as prefix in log
+    :type id: int
+    :param id: used as prefix in log
         statements. The default value is empty string, which is OK if
         there is only one app. instance. Example:
         
@@ -139,6 +141,7 @@ commentVerifier.check(doxygen_misc_constructs.cycle.__doc__,
             main_ctrl.setBP("func1");
         
 
-      fileName (char *) -- name of the log file
+    :type fileName: char *
+    :param fileName: name of the log file
     """
 );

Examples/test-suite/python/doxygen_parsing_runme.py

@@ -27,18 +27,20 @@ commentVerifier.check(doxygen_parsing.SomeAnotherClass.classMethodExtended.__doc
     r"""
         The class method with parameter
 
-        Arguments:
-          a (int) -- Parameter a
-          b (int) -- Parameter b
+        :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
 
-        Arguments:
-          a (int) -- Parameter a
-          b (int) -- Parameter b
+        :type a: int
+        :param a: Parameter a
+        :type b: int
+        :param b: Parameter b
         """
 )
 commentVerifier.check(doxygen_parsing.SomeAnotherStruct.structMethod.__doc__,
@@ -49,16 +51,18 @@ commentVerifier.check(doxygen_parsing.SomeAnotherStruct.structMethodExtended.__d
     r"""
         The struct method with parameter
 
-        Arguments:
-          a (int) -- Parameter a
-          b (int) -- Parameter b
+        :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
 
-        Arguments:
-          a (int) -- Parameter a
-          b (int) -- Parameter b
+        :type a: int
+        :param a: Parameter a
+        :type b: int
+        :param b: Parameter b
         """)

Examples/test-suite/python/doxygen_translate_all_tags_runme.py

@@ -79,7 +79,7 @@ r"""
 
     _italicword_
 
-    emphazedWord 
+    emphazedWord
 
 
 
@@ -89,7 +89,7 @@ r"""
 
 commentVerifier.check(doxygen_translate_all_tags.func04.__doc__,
 r"""
-    Throws: SuperError
+    :raises: SuperError
 
 
 
@@ -219,8 +219,8 @@ r"""
 
 
 
-    Arguments:
-      a (int) -- the first param
+    :type a: int
+    :param a: the first param
 
 
 
@@ -255,11 +255,11 @@ r"""
 
     Another remarks section
 
-    Return: Whatever
+    :return: Whatever
 
-    it
+    :return: it
 
-    Returns: may return
+    :return: may return
 
     """)
 
@@ -295,17 +295,17 @@ r"""
 
 
 
-    Throw: superException
+    :raises: superException
 
-    Throws: RuntimeError
+    :raises: RuntimeError
     """)
 
 commentVerifier.check(doxygen_translate_all_tags.func10.__doc__,
 r"""
     TODO: Some very important task
 
-    Arguments:
-      b (float) -- B is mentioned again...
+    :type b: float
+    :param b: B is mentioned again...
 
 
 

Examples/test-suite/python/doxygen_translate_runme.py

@@ -37,7 +37,7 @@ r"""
     Example: someFile.txt
     Some details on using the example
 
-    Throws: SuperError
+    :raises: SuperError
 
     If: ANOTHERCONDITION {
       First part of comment
@@ -88,18 +88,18 @@ r"""
     The paragraph text.
     Maybe even multiline
 
-    Arguments:
-      a (int) -- the first param
+    :type a: int
+    :param a: the first param
 
     Remarks: Some remark text
 
     Another remarks section
 
-    Return: Whatever
+    :return: Whatever
 
-    it
+    :return: it
 
-    Returns: may return
+    :return: may return
 
     See also: someOtherMethod
 
@@ -107,14 +107,14 @@ r"""
 
     Since: version 0.0.0.1
 
-    Throw: superException
+    :raises: superException
 
-    Throws: RuntimeError
+    :raises: RuntimeError
 
     TODO: Some very important task
 
-    Arguments:
-      b (float) -- B is mentioned again...
+    :type b: float
+    :param b: B is mentioned again...
 
 
     very long
@@ -225,8 +225,8 @@ commentVerifier.check(doxygen_translate.htmlTableFunction.__doc__,
 r"""
     The meaning of flags:
 
-    Arguments:
-      byFlags (int) -- bits marking required items:
+    :type byFlags: int
+    :param byFlags: bits marking required items:
       
       | Size in bits| Items Required |
       --------------------------------