gmmproc: _WRAP_METHOD: Accept optional list of exceptions in errthrow

In _WRAP_METHOD[_DOCS_ONLY], the errthrow parameter can now contain an
optional list of exceptions with default value Glib::Error.
Corresponding @throws Doxygen commands are included in the documentation,
if the documentation does not contain other @throws commands (e.g.
from *_docs_override.xml). Bug 787979

3 files changed, 34 insertions, 9 deletions

diff --git a/tools/pm/DocsParser.pm b/tools/pm/DocsParser.pm
index e9f308b3..137826f6 100644
--- a/tools/pm/DocsParser.pm
+++ b/tools/pm/DocsParser.pm
@@ -327,16 +327,17 @@ sub lookup_enum_documentation($$$$$$$)
   return $docs;
 }
 
-# $strCommentBlock lookup_documentation($strFunctionName, $deprecation_docs, $newin, $objCppfunc)
+# $strCommentBlock lookup_documentation($strFunctionName, $deprecation_docs,
+#   $newin, $errthrow, $objCppfunc)
 # The final objCppfunc parameter is optional. If 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, $objCppfunc) = @_;
+  my ($functionName, $deprecation_docs, $newin, $errthrow, $objCppfunc) = @_;
 
   my $objFunction = $DocsParser::hasharrayFunctions{$functionName};
   if(!$objFunction)
@@ -370,6 +371,8 @@ sub lookup_documentation($$$;$)
   {
     DocsParser::append_return_docs($objFunction, \$text);
   }
+  DocsParser::add_throws(\$text, $errthrow);
+
   # Convert C parameter names to C++ parameter names where they differ.
   foreach my $key (keys %param_name_mappings)
   {
@@ -748,6 +751,24 @@ 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.
+sub add_throws($$)
+{
+  my ($text, $errthrow) = @_;
+
+  return if ($errthrow eq "");
+
+  if (!($$text =~ /[\@\\](throws?|exception)\b/))
+  {
+    # Each comma, not preceded by backslash, creates a new @throws command.
+    $errthrow =~ s/([^\\]),\s*/$1\n\@throws /g;
+    $errthrow =~ s/\\,/,/g; # Delete backslash before comma
+    $$text .= "\n\n\@throws $errthrow";
+  }
+}
+
 # Convert <simplelist> tags to a list of newline-separated elements.
 sub convert_simplelist($)
 {
diff --git a/tools/pm/Output.pm b/tools/pm/Output.pm
index f0a011ae..2bd18e92 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 cb3337ad..21d3287f 100644
--- a/tools/pm/WrapParser.pm
+++ b/tools/pm/WrapParser.pm
@@ -946,6 +946,7 @@ sub on_wrap_method($)
   $$objCfunc{throw_any_errors} = 0;
   $$objCfunc{constversion} = 0;
   $$objCfunc{deprecated} = "";
+  my $errthrow_docs = "";
   my $deprecation_docs = "";
   my $newin = "";
   my $ifdef;
@@ -957,9 +958,10 @@ sub on_wrap_method($)
     {
       $$objCfunc{rettype_needs_ref} = 1;
     }
-    elsif($argRef eq "errthrow")
+    elsif($argRef =~ /^errthrow(.*)/) #If errthrow is at the start.
     {
       $$objCfunc{throw_any_errors} = 1;
+      $errthrow_docs = ($1 ne "") ? string_unquote(string_trim($1)) : "Glib::Error";
     }
     elsif($argRef eq "constversion")
     {
@@ -1010,7 +1012,7 @@ sub on_wrap_method($)
   else
   {
     $commentblock = DocsParser::lookup_documentation($argCFunctionName,
-      $deprecation_docs, $newin, $objCppfunc);
+      $deprecation_docs, $newin, $errthrow_docs, $objCppfunc);
   }
 
   $objOutputter->output_wrap_meth($filename, $line_num, $objCppfunc, $objCfunc, $argCppMethodDecl, $commentblock, $ifdef);
@@ -1060,13 +1062,15 @@ sub on_wrap_method_docs_only($)
   }
 
   $$objCfunc{throw_any_errors} = 0;
+  my $errthrow_docs = "";
   my $newin = "";
   while($#args >= 1) # If the optional ref/err arguments are there.
   {
     my $argRef = string_trim(pop @args);
-    if($argRef eq "errthrow")
+    if($argRef =~ /^errthrow(.*)/) #If errthrow is at the start.
     {
       $$objCfunc{throw_any_errors} = 1;
+      $errthrow_docs = ($1 ne "") ? string_unquote(string_trim($1)) : "Glib::Error";
     }
     elsif($argRef =~ /^newin(.*)/) #If newin is at the start.
     {
@@ -1075,7 +1079,7 @@ sub on_wrap_method_docs_only($)
   }
 
   my $commentblock = "";
-  $commentblock = DocsParser::lookup_documentation($argCFunctionName, "", $newin);
+  $commentblock = DocsParser::lookup_documentation($argCFunctionName, "", $newin, $errthrow_docs);
   $objOutputter->output_wrap_meth_docs_only($filename, $line_num, $commentblock);
 }