Flag optional arguments in doxygen pydoc output

If the parameter has a default value, add the string ", optional" to
the parameter type description in the translated python comments.
Three examples with default values were already present in the test
cases, so their expected python output has been updated accordingly.

Examples/test-suite/python/doxygen_basic_translate_runme.py

@@ -60,7 +60,7 @@ comment_verifier.check(inspect.getdoc(doxygen_basic_translate.function5),
 comment_verifier.check(inspect.getdoc(doxygen_basic_translate.function6),
     """\
 Test for default args
-:type a: int
+:type a: int, optional
 :param a: Some parameter, default is 42"""
 )
 comment_verifier.check(inspect.getdoc(doxygen_basic_translate.function7),

Examples/test-suite/python/doxygen_basic_translate_style2_runme.py

@@ -58,7 +58,7 @@ comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style2.function5),
 comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style2.function6),
     """\
 Test for default args
-:type a: int
+:type a: int, optional
 :param a: Some parameter, default is 42"""
 )
 comment_verifier.check(inspect.getdoc(doxygen_basic_translate_style2.function7),

Examples/test-suite/python/doxygen_misc_constructs_runme.py

@@ -12,7 +12,7 @@ comment_verifier.check(inspect.getdoc(doxygen_misc_constructs.getAddress),
 :param fileName: name of the file, where the source line is located
 :type line: int
 :param line: line number
-:type isGetSize: boolean
+:type isGetSize: boolean, optional
 :param isGetSize: if set, for every object location both address and size are returned
 
 Connection::getId() """)

Source/Doxygen/pydoc.cxx

@@ -443,6 +443,23 @@ std::string PyDocConverter::getParamType(std::string param) {
   return type;
 }
 
+std::string PyDocConverter::getParamValue(std::string param) {
+  std::string value;
+
+  ParmList *plist = CopyParmList(Getattr(currentNode, "parms"));
+  for (Parm *p = plist; p; p = nextSibling(p)) {
+    String *pname = Getattr(p, "name");
+    if (Char(pname) != param)
+      continue;
+
+    String *pval = Getattr(p, "value");
+    if (pval) value = Char(pval);
+    break;
+  }
+  Delete(plist);
+  return value;
+}
+
 std::string PyDocConverter::translateSubtree(DoxygenEntity &doxygenEntity) {
   std::string translatedComment;
 
@@ -651,6 +668,7 @@ void PyDocConverter::handleTagParam(DoxygenEntity &tag, std::string &translatedC
   const std::string &paramName = paramNameEntity.data;
 
   const std::string paramType = getParamType(paramName);
+  const std::string paramValue = getParamValue(paramName);
 
   // Get command option, e.g. "in", "out", or "in,out"
   string commandOpt = getCommandOption(tag.typeOfEntity);
@@ -662,6 +680,12 @@ void PyDocConverter::handleTagParam(DoxygenEntity &tag, std::string &translatedC
   if (commandOpt.size() > 0)
     suffix = ", " + commandOpt;
   
+  // If the parameter has a default value, flag it as optional in the
+  // generated type definition.  Particularly helpful when the python
+  // call is generated with *args, **kwargs.
+  if (paramValue.size() > 0)
+    suffix += ", optional";  
+
   if (!paramType.empty()) {
     translatedComment += ":type " + paramName + ": " + paramType + suffix + "\n";
     translatedComment += indent.getFirstLineIndent();

Source/Doxygen/pydoc.h

@@ -178,6 +178,11 @@ protected:
    */
   std::string getParamType(std::string name);
 
+  /*
+   * Simple helper function to retrieve the parameter value
+   */
+  std::string getParamValue(std::string name);
+
 private:
   // temporary thing, should be refactored somehow
   Node *currentNode;