gmmproc, _WRAP_METHOD_DOCS_ONLY: Optionally suppress @return section

Add an optional 'voidreturn' parameter that can be specified if the wrapped
C function returns a value, but the corresponding C++ method returns void.
Bug 787978

3 files changed, 18 insertions, 12 deletions

diff --git a/tools/pm/DocsParser.pm b/tools/pm/DocsParser.pm
index 137826f6..fb6d55cc 100644
--- a/tools/pm/DocsParser.pm
+++ b/tools/pm/DocsParser.pm
@@ -328,16 +328,16 @@ sub lookup_enum_documentation($$$$$$$)
 }
 
 # $strCommentBlock lookup_documentation($strFunctionName, $deprecation_docs,
-#   $newin, $errthrow, $objCppfunc)
-# The final objCppfunc parameter is optional. If passed, it is used for
+#   $newin, $objCppfunc, $errthrow, $voidreturn)
+# The parameters from objCppfunc are optional. If objCppfunc is passed, it is used for
 # - deciding if the final C parameter shall be omitted if the C++ method
 #   has a slot parameter,
 # - converting C parameter names to C++ parameter names in the documentation,
 #   if they differ,
 # - deciding if the @return section shall be omitted.
-sub lookup_documentation($$$$;$)
+sub lookup_documentation($$$;$$$)
 {
-  my ($functionName, $deprecation_docs, $newin, $errthrow, $objCppfunc) = @_;
+  my ($functionName, $deprecation_docs, $newin, $objCppfunc, $errthrow, $voidreturn) = @_;
 
   my $objFunction = $DocsParser::hasharrayFunctions{$functionName};
   if(!$objFunction)
@@ -367,7 +367,7 @@ sub lookup_documentation($$$$;$)
   }
 
   my %param_name_mappings = DocsParser::append_parameter_docs($objFunction, \$text, $objCppfunc);
-  if (!(defined($objCppfunc) && $$objCppfunc{rettype} eq "void"))
+  unless ((defined($objCppfunc) && $$objCppfunc{rettype} eq "void") || $voidreturn)
   {
     DocsParser::append_return_docs($objFunction, \$text);
   }
@@ -752,13 +752,13 @@ sub replace_or_add_newin($$)
 }
 
 # void add_throws(\$text, $errthrow)
-# If $errthrow is not empty, and $$text does not contain a @throw, @throws
-# or @exception Doxygen command, add one or more @throws commands.
+# If $errthrow is defined and not empty, and $$text does not contain a @throw,
+# @throws or @exception Doxygen command, add one or more @throws commands.
 sub add_throws($$)
 {
   my ($text, $errthrow) = @_;
 
-  return if ($errthrow eq "");
+  return if (!defined($errthrow) or $errthrow eq "");
 
   if (!($$text =~ /[\@\\](throws?|exception)\b/))
   {
diff --git a/tools/pm/Output.pm b/tools/pm/Output.pm
index 2bd18e92..f0a011ae 100644
--- a/tools/pm/Output.pm
+++ b/tools/pm/Output.pm
@@ -626,7 +626,7 @@ sub output_wrap_sig_decl($$$$$$$$$$$$$$)
 
   # Get the existing signal documentation from the parsed docs.
   my $documentation = DocsParser::lookup_documentation(
-    "$$objCSignal{class}::$underscored_signal_name", $deprecation_docs, $newin, "", $objCppfunc);
+    "$$objCSignal{class}::$underscored_signal_name", $deprecation_docs, $newin, $objCppfunc);
 
   # Create a merged Doxygen comment block for the signal from the looked up
   # docs (the block will also contain a prototype of the slot as an example).
@@ -875,7 +875,7 @@ sub output_wrap_any_property($$$$$$$$$$)
 
   # Get the existing property documentation, if any, from the parsed docs.
   my $documentation = DocsParser::lookup_documentation(
-    "$$objProperty{class}:$name_underscored", $deprecation_docs, $newin, "");
+    "$$objProperty{class}:$name_underscored", $deprecation_docs, $newin);
 
   if ($documentation ne "")
   {
diff --git a/tools/pm/WrapParser.pm b/tools/pm/WrapParser.pm
index 21d3287f..ac2ed979 100644
--- a/tools/pm/WrapParser.pm
+++ b/tools/pm/WrapParser.pm
@@ -1012,7 +1012,7 @@ sub on_wrap_method($)
   else
   {
     $commentblock = DocsParser::lookup_documentation($argCFunctionName,
-      $deprecation_docs, $newin, $errthrow_docs, $objCppfunc);
+      $deprecation_docs, $newin, $objCppfunc, $errthrow_docs);
   }
 
   $objOutputter->output_wrap_meth($filename, $line_num, $objCppfunc, $objCfunc, $argCppMethodDecl, $commentblock, $ifdef);
@@ -1064,6 +1064,7 @@ sub on_wrap_method_docs_only($)
   $$objCfunc{throw_any_errors} = 0;
   my $errthrow_docs = "";
   my $newin = "";
+  my $voidreturn = 0;
   while($#args >= 1) # If the optional ref/err arguments are there.
   {
     my $argRef = string_trim(pop @args);
@@ -1076,10 +1077,15 @@ sub on_wrap_method_docs_only($)
     {
       $newin = string_unquote(string_trim($1));
     }
+    elsif($argRef eq "voidreturn")
+    {
+      $voidreturn = 1;
+    }
   }
 
   my $commentblock = "";
-  $commentblock = DocsParser::lookup_documentation($argCFunctionName, "", $newin, $errthrow_docs);
+  $commentblock = DocsParser::lookup_documentation($argCFunctionName, "", $newin,
+    undef, $errthrow_docs, $voidreturn);
   $objOutputter->output_wrap_meth_docs_only($filename, $line_num, $commentblock);
 }