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:
+    :type a: int
-      a (int) -- Some parameter, default is 42
+    :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:
+    :type a: Shape::superType *[10]
-      a (Shape::superType *[10]) -- Very strange param
+    :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:
+    :type fileName: int &
-      fileName (int &) -- name of the file, where the source line is located
+    :param fileName: name of the file, where the source line is located
-      line (int) -- line number
+    :type line: int
-      isGetSize (bool) -- if set, for every object location both address and size are returned
+    :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:
+    :type id: int
-      id (int) -- used as prefix in log
+    :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:
+        :type a: int
-          a (int) -- Parameter a
+        :param a: Parameter a
-          b (int) -- Parameter b
+        :type b: int
+        :param b: Parameter b
         """
 )
 commentVerifier.check(doxygen_parsing.SomeAnotherClass.classMethodExtended2.__doc__, 
     r"""
         The class method with parameter
 
-        Arguments:
+        :type a: int
-          a (int) -- Parameter a
+        :param a: Parameter a
-          b (int) -- Parameter b
+        :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:
+        :type a: int
-          a (int) -- Parameter a
+        :param a: Parameter a
-          b (int) -- Parameter b
+        :type b: int
+        :param b: Parameter b
         """
 )
 commentVerifier.check(doxygen_parsing.SomeAnotherStruct.structMethodExtended2.__doc__,
     r"""
         The struct method with parameter
 
-        Arguments:
+        :type a: int
-          a (int) -- Parameter a
+        :param a: Parameter a
-          b (int) -- Parameter b
+        :type b: int
+        :param b: Parameter b
         """)

Examples/test-suite/python/doxygen_translate_all_tags_runme.py

@@ -89,7 +89,7 @@ r"""
 
 commentVerifier.check(doxygen_translate_all_tags.func04.__doc__,
 r"""
-    Throws: SuperError
+    :raises: SuperError
 
 
 
@@ -219,8 +219,8 @@ r"""
 
 
 
-    Arguments:
+    :type a: int
-      a (int) -- the first param
+    :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:
+    :type b: float
-      b (float) -- B is mentioned again...
+    :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:
+    :type a: int
-      a (int) -- the first param
+    :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:
+    :type b: float
-      b (float) -- B is mentioned again...
+    :param b: B is mentioned again...
 
 
     very long
@@ -225,8 +225,8 @@ commentVerifier.check(doxygen_translate.htmlTableFunction.__doc__,
 r"""
     The meaning of flags:
 
-    Arguments:
+    :type byFlags: int
-      byFlags (int) -- bits marking required items:
+    :param byFlags: bits marking required items:
       
       | Size in bits| Items Required |
       --------------------------------

Source/DoxygenTranslator/src/PyDocConverter.cpp

@@ -50,21 +50,13 @@ void PyDocConverter::fillStaticTables()
   sectionTitles["copyright"] = "Copyright: ";
   sectionTitles["deprecated"] = "Deprecated: ";
   sectionTitles["example"] = "Example: ";
-  sectionTitles["exception"] = "Throws: ";
-  sectionTitles["param"] = "Arguments:\n";
-  sectionTitles["tparam"] = "Arguments:\n";
   sectionTitles["note"] = "Notes: ";
   sectionTitles["remark"] = "Remarks: ";
   sectionTitles["remarks"] = "Remarks: ";
   sectionTitles["warning"] = "Warning: ";
-  sectionTitles["result"] = "Return: ";
-  sectionTitles["return"] = "Return: ";
-  sectionTitles["returns"] = "Returns: ";
 //  sectionTitles["sa"] = "See also: ";
 //  sectionTitles["see"] = "See also: ";
   sectionTitles["since"] = "Since: ";
-  sectionTitles["throw"] = "Throw: ";
-  sectionTitles["throws"] = "Throws: ";
   sectionTitles["todo"] = "TODO: ";
   sectionTitles["version"] = "Version: ";
 
@@ -100,7 +92,9 @@ void PyDocConverter::fillStaticTables()
   tagHandlers["details"] = make_handler(&PyDocConverter::handleParagraph);
   tagHandlers["em"] = make_handler(&PyDocConverter::handleParagraph, " ");
   tagHandlers["example"] = make_handler(&PyDocConverter::handleParagraph);
-  tagHandlers["exception"] = make_handler(&PyDocConverter::handleParagraph);
+  tagHandlers["exception"] =
+  tagHandlers["throw"] =
+  tagHandlers["throws"] = make_handler(&PyDocConverter::handleTagException);
   tagHandlers["htmlonly"] = make_handler(&PyDocConverter::handleParagraph);
   tagHandlers["invariant"] = make_handler(&PyDocConverter::handleParagraph);
   tagHandlers["latexonly"] = make_handler(&PyDocConverter::handleParagraph);
@@ -110,9 +104,6 @@ void PyDocConverter::fillStaticTables()
   tagHandlers["p"] = make_handler(&PyDocConverter::handleParagraph);
   tagHandlers["partofdescription"] = make_handler(&PyDocConverter::handleParagraph);
   tagHandlers["rtfonly"] = make_handler(&PyDocConverter::handleParagraph);
-  tagHandlers["return"] = make_handler(&PyDocConverter::handleParagraph);
-  tagHandlers["returns"] = make_handler(&PyDocConverter::handleParagraph);
-  tagHandlers["result"] = make_handler(&PyDocConverter::handleParagraph);
   tagHandlers["remark"] = make_handler(&PyDocConverter::handleParagraph);
   tagHandlers["remarks"] = make_handler(&PyDocConverter::handleParagraph);
   tagHandlers["sa"] = make_handler(&PyDocConverter::handleTagMessage, "See also: ");
@@ -120,8 +111,6 @@ void PyDocConverter::fillStaticTables()
       "See also: ");
   tagHandlers["since"] = make_handler(&PyDocConverter::handleParagraph);
   tagHandlers["short"] = make_handler(&PyDocConverter::handleParagraph);
-  tagHandlers["throw"] = make_handler(&PyDocConverter::handleParagraph);
-  tagHandlers["throws"] = make_handler(&PyDocConverter::handleParagraph);
   tagHandlers["todo"] = make_handler(&PyDocConverter::handleParagraph);
   tagHandlers["version"] = make_handler(&PyDocConverter::handleParagraph);
   tagHandlers["verbatim"] = make_handler(&PyDocConverter::handleParagraph);
@@ -144,9 +133,13 @@ void PyDocConverter::fillStaticTables()
           " convenience.\nIt differs from the above function only in what"
           " argument(s) it accepts.");
   tagHandlers["par"] = make_handler(&PyDocConverter::handleTagPar);
-  tagHandlers["param"] = make_handler(&PyDocConverter::handleTagParam);
+  tagHandlers["param"] =
   tagHandlers["tparam"] = make_handler(&PyDocConverter::handleTagParam);
   tagHandlers["ref"] = make_handler(&PyDocConverter::handleTagRef);
+  tagHandlers["result"] =
+  tagHandlers["return"] =
+  tagHandlers["returns"] = make_handler(&PyDocConverter::handleTagReturn);
+
   // this command just prints it's contents
   // (it is internal command of swig's parser, contains plain text)
   tagHandlers["plainstd::string"] = make_handler(&PyDocConverter::handlePlainString);
@@ -417,11 +410,31 @@ void PyDocConverter::handleTagParam(DoxygenEntity& tag,
   DoxygenEntity paramNameEntity = *tag.entityList.begin();
   tag.entityList.pop_front();
 
-  std::string paramType = getParamType(paramNameEntity.data);
+  const std::string& paramName = paramNameEntity.data;
-  if (!paramType.size())
-    paramType = "none";
 
-  translatedComment += "  " + paramNameEntity.data + " (" + paramType + ") --";
+  const std::string paramType = getParamType(paramName);
+  if (!paramType.empty())
+    translatedComment += ":type " + paramName + ": " + paramType + "\n";
+
+  translatedComment += ":param " + paramName + ":";
+  handleParagraph(tag, translatedComment);
+}
+
+
+void PyDocConverter::handleTagReturn(DoxygenEntity &tag,
+                                     std::string &translatedComment,
+                                     const std::string &)
+{
+  translatedComment += ":return: ";
+  handleParagraph(tag, translatedComment);
+}
+
+
+void PyDocConverter::handleTagException(DoxygenEntity &tag,
+                                        std::string &translatedComment,
+                                        const std::string &)
+{
+  translatedComment += ":raises: ";
   handleParagraph(tag, translatedComment);
 }
 

Source/DoxygenTranslator/src/PyDocConverter.h

@@ -71,6 +71,10 @@ protected:
    * Print the name of tag to the output, used for escape-commands
    */
   void handleTagChar(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg);
+  /*
+   * Format the contents of the \exception tag or its synonyms.
+   */
+  void handleTagException(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg);
   /*
    * Print only the content and strip original tag
    */
@@ -109,6 +113,10 @@ protected:
    * Format nice param description with type information
    */
   void handleTagParam(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg);
+  /*
+   * Format the contents of the \return tag or its synonyms.
+   */
+  void handleTagReturn(DoxygenEntity &tag, std::string &translatedComment, const std::string &arg);
   /*
    * Writes text for \ref tag. 
    */