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.

2 files changed, 29 insertions, 0 deletions

diff --git a/Source/Doxygen/pydoc.cxx b/Source/Doxygen/pydoc.cxx
index 0238cbfa4..579b144ca 100644
--- a/Source/Doxygen/pydoc.cxx
+++ b/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);
@@ -661,6 +679,12 @@ void PyDocConverter::handleTagParam(DoxygenEntity &tag, std::string &translatedC
   std::string suffix;
   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";
diff --git a/Source/Doxygen/pydoc.h b/Source/Doxygen/pydoc.h
index df8997d76..07c5ce51e 100644
--- a/Source/Doxygen/pydoc.h
+++ b/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;