From fd33bdf8a5cd8986297febb2676adb35d8acff90 Mon Sep 17 00:00:00 2001
From: John McFarland <mcfarljm@gmail.com>
Date: Sat, 3 Aug 2019 10:31:57 -0500
Subject: [PATCH] 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.
---
 .../python/doxygen_basic_translate_runme.py   |  2 +-
 .../doxygen_basic_translate_style2_runme.py   |  2 +-
 .../python/doxygen_misc_constructs_runme.py   |  2 +-
 Source/Doxygen/pydoc.cxx                      | 24 +++++++++++++++++++
 Source/Doxygen/pydoc.h                        |  5 ++++
 5 files changed, 32 insertions(+), 3 deletions(-)

diff --git a/Examples/test-suite/python/doxygen_basic_translate_runme.py b/Examples/test-suite/python/doxygen_basic_translate_runme.py
index 9ef8dbd52..90edda132 100644
--- a/Examples/test-suite/python/doxygen_basic_translate_runme.py
+++ b/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),
diff --git a/Examples/test-suite/python/doxygen_basic_translate_style2_runme.py b/Examples/test-suite/python/doxygen_basic_translate_style2_runme.py
index b75045d59..a24f5defc 100644
--- a/Examples/test-suite/python/doxygen_basic_translate_style2_runme.py
+++ b/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),
diff --git a/Examples/test-suite/python/doxygen_misc_constructs_runme.py b/Examples/test-suite/python/doxygen_misc_constructs_runme.py
index 11aa53ba3..c0b5c1620 100644
--- a/Examples/test-suite/python/doxygen_misc_constructs_runme.py
+++ b/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() """)
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;