gmmproc: Add support for 'newin "n,m"' in some _WRAP macros

* tools/pm/DocsParser.pm:
* tools/pm/Enum.pm:
* tools/pm/Output.pm:
* tools/pm/WrapParser.pm: Add support for the optional 'newin "n,m"' parameter
in _WRAP_METHOD, _WRAP_METHOD_DOCS_ONLY, _WRAP_SIGNAL, _WRAP_ENUM,
_WRAP_ENUM_DOCS_ONLY and _WRAP_GERRROR. Bug #748856.

4 files changed, 75 insertions, 31 deletions

diff --git a/tools/pm/DocsParser.pm b/tools/pm/DocsParser.pm
index 0e9e66fd..3cfac2d3 100644
--- a/tools/pm/DocsParser.pm
+++ b/tools/pm/DocsParser.pm
@@ -25,7 +25,7 @@ use XML::Parser;
 use strict;
 use warnings;
 
-# use Util;
+use Util;
 use Function;
 use GtkDefs;
 use Object;
@@ -239,8 +239,9 @@ sub lookup_enum_documentation($$$$)
   
   my @subst_in  = [];
   my @subst_out = [];
+  my $newin = "";
  
- # Get the substitutions.
+ # Get the substitutions, and recognize some flags too.
   foreach(@$ref_flags)
   {
     if(/^\s*s#([^#]+)#([^#]*)#\s*$/)
@@ -248,6 +249,10 @@ sub lookup_enum_documentation($$$$)
       push(@subst_in,  $1);
       push(@subst_out, $2);
     }
+    elsif(/^\s*newin(.*)/) #If newin is at the start.
+    {
+      $newin = string_unquote(string_trim($1));
+    }
   }
 
   my $objFunction = $DocsParser::hasharrayFunctions{$c_enum_name};
@@ -293,11 +298,15 @@ sub lookup_enum_documentation($$$$)
     }
   }
 
-  # Append the enum description docs.
-  $docs .= "\@enum $cpp_enum_name\n"; 
-  $docs .= $$objFunction{description};
+  # Replace @newin in the enum description, but don't in the element descriptions.
+  my $description = "\@enum $cpp_enum_name\n";
+  $description .= $$objFunction{description};
+  DocsParser::convert_docs_to_cpp($objFunction, \$description);
+  DocsParser::replace_or_add_newin(\$description, $newin);
 
+  # Append the enum description docs.
   DocsParser::convert_docs_to_cpp($objFunction, \$docs);
+  $docs .= "\n\n$description";
   DocsParser::add_m4_quotes(\$docs);
 
   # Escape the space after "i.e." or "e.g." in the brief description.
@@ -312,13 +321,13 @@ sub lookup_enum_documentation($$$$)
   return $docs;
 }
 
-# $strCommentBlock lookup_documentation($strFunctionName, $deprecation_docs, $objCppfunc)
+# $strCommentBlock lookup_documentation($strFunctionName, $deprecation_docs, $newin, $objCppfunc)
 # The final objCppfunc parameter is optional.  If passed, it is used to
 # decide if the final C parameter should be omitted if the C++ method
 # has a slot parameter.
-sub lookup_documentation($$;$)
+sub lookup_documentation($$$;$)
 {
-  my ($functionName, $deprecation_docs, $objCppfunc) = @_;
+  my ($functionName, $deprecation_docs, $newin, $objCppfunc) = @_;
 
   my $objFunction = $DocsParser::hasharrayFunctions{$functionName};
   if(!$objFunction)
@@ -335,6 +344,7 @@ sub lookup_documentation($$;$)
   }
 
   DocsParser::convert_docs_to_cpp($objFunction, \$text);
+  DocsParser::replace_or_add_newin(\$text, $newin);
   # A blank line, marking the end of a paragraph, is needed after @newin.
   # Most @newins are at the end of a function description.
   $text .= "\n";
@@ -547,6 +557,21 @@ sub convert_tags_to_doxygen($)
   }
 }
 
+# void replace_or_add_newin(\$text, $newin)
+# If $newin is not empty, replace the version numbers in an existing @newin
+# Doxygen alias, or add one if there is none.
+sub replace_or_add_newin($$)
+{
+  my ($text, $newin) = @_;
+
+  return if ($newin eq "");
+
+  if (!($$text =~ s/\@newin\{[\d,]+\}/\@newin{$newin}/))
+  {
+    $$text .= "\n\n\@newin{$newin}";
+  }
+}
+
 # Convert <simplelist> tags to a list of newline-separated elements.
 sub convert_simplelist($)
 {
diff --git a/tools/pm/Enum.pm b/tools/pm/Enum.pm
index 8d0ce774..61840771 100644
--- a/tools/pm/Enum.pm
+++ b/tools/pm/Enum.pm
@@ -300,7 +300,7 @@ sub build_element_list($$$$)
       push(@subst_in,  $1);
       push(@subst_out, $2);
     }
-    elsif($_ !~ /^\s*$/)
+    elsif($_ !~ /^\s*(?:newin.*)?$/) # newin or only white space
     {
       return undef;
     }
diff --git a/tools/pm/Output.pm b/tools/pm/Output.pm
index 3ae40d5a..dc1fe83f 100644
--- a/tools/pm/Output.pm
+++ b/tools/pm/Output.pm
@@ -583,11 +583,14 @@ sub output_wrap_create($$$)
   }
 }
 
-# void output_wrap_sig_decl($filename, $line_num, $objCSignal, $objCppfunc, $signal_name, $bCustomCCallback, $ifdef, $commentblock, $deprecated, $deprecation_docs, $exceptionHandler)
-# custom_signalproxy_name is "" when no type conversion is required - a normal templates SignalProxy will be used instead.
-sub output_wrap_sig_decl($$$$$$$$$$$)
+# void output_wrap_sig_decl($filename, $line_num, $objCSignal, $objCppfunc, $signal_name,
+#   $bCustomCCallback, $ifdef, $commentblock, $deprecated, $deprecation_docs,
+#   $newin, $exceptionHandler)
+sub output_wrap_sig_decl($$$$$$$$$$$$)
 {
-  my ($self, $filename, $line_num, $objCSignal, $objCppfunc, $signal_name, $bCustomCCallback, $ifdef, $commentblock, $deprecated, $deprecation_docs, $exceptionHandler) = @_;
+  my ($self, $filename, $line_num, $objCSignal, $objCppfunc, $signal_name,
+      $bCustomCCallback, $ifdef, $commentblock, $deprecated, $deprecation_docs,
+      $newin, $exceptionHandler) = @_;
 
 # _SIGNAL_PROXY(c_signal_name, c_return_type, `<c_arg_types_and_names>',
 #               cpp_signal_name, cpp_return_type, `<cpp_arg_types>',`<c_args_to_cpp>',
@@ -599,8 +602,8 @@ sub output_wrap_sig_decl($$$$$$$$$$$)
   $underscored_signal_name =~ s/-/_/g;
 
   # Get the existing signal documentation from the parsed docs.
-  my $documentation =
-    DocsParser::lookup_documentation("$$objCSignal{class}::$underscored_signal_name", $deprecation_docs);
+  my $documentation = DocsParser::lookup_documentation(
+    "$$objCSignal{class}::$underscored_signal_name", $deprecation_docs, $newin);
 
   # 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).
@@ -713,7 +716,7 @@ sub output_wrap_enum_docs_only($$$$$$$)
   }
 
   # Include the enum docs in the module's enum docs group.
-  $enum_docs .= "\n * \@ingroup ${module_canonical}Enums\n";
+  $enum_docs .= "\n *\n * \@ingroup ${module_canonical}Enums";
 
   # Merge the passed in comment to the existing enum documentation.
   $comment = "/** " . $comment . "\n * " . $enum_docs . "\n */\n";
diff --git a/tools/pm/WrapParser.pm b/tools/pm/WrapParser.pm
index 2e29d4da..56dbf458 100644
--- a/tools/pm/WrapParser.pm
+++ b/tools/pm/WrapParser.pm
@@ -702,11 +702,12 @@ sub extract_bracketed_text($)
 
 ########################################
 ###  breaks up a string by commas (smart)
-# @strings string_split_commas($string)
-sub string_split_commas($)
+# @strings string_split_commas($string [, $ignore_quotes])
+sub string_split_commas($;$)
 {
-  my ($in) = @_;
+  my ($in, $ignore_quotes) = @_;
 
+  $ignore_quotes = 2 unless defined $ignore_quotes;
   my @out;
   my $level = 0;
   my $in_braces = 0;
@@ -720,10 +721,10 @@ sub string_split_commas($)
 
     next if ($t eq "");
 
-    # TODO: Delete the test for scalar(@out) >= 2 when we can stop accepting
+    # TODO: Delete the test for scalar(@out) >= $ignore_quotes when we can stop accepting
     # .hg files with unpaired quotes, such as _WRAP_PROPERTY("text_column, int).
     # See also TODO in extract_bracketed_text().
-    $in_quotes = !$in_quotes if ($t eq '"' and scalar(@out) >= 2);
+    $in_quotes = !$in_quotes if ($t eq '"' and scalar(@out) >= $ignore_quotes);
     if (!$in_quotes)
     {
       $in_braces++ if ($t eq "{");
@@ -950,6 +951,7 @@ sub on_wrap_method($)
   $$objCfunc{constversion} = 0;
   $$objCfunc{deprecated} = "";
   my $deprecation_docs = "";
+  my $newin = "";
   my $ifdef;
   while($#args >= 2) # If the optional ref/err/deprecated arguments are there.
   {
@@ -976,6 +978,10 @@ sub on_wrap_method($)
         $deprecation_docs = string_unquote(string_trim($1));
       }
     }
+    elsif($argRef =~ /^newin(.*)/) #If newin is at the start.
+    {
+      $newin = string_unquote(string_trim($1));
+    }
     elsif($argRef =~ /^ifdef(.*)/) #If ifdef is at the start.
     {
     	$ifdef = $1;
@@ -1008,7 +1014,7 @@ sub on_wrap_method($)
   else
   {
     $commentblock = DocsParser::lookup_documentation($argCFunctionName,
-      $deprecation_docs, $objCppfunc);
+      $deprecation_docs, $newin, $objCppfunc);
   }
 
   $objOutputter->output_wrap_meth($filename, $line_num, $objCppfunc, $objCfunc, $argCppMethodDecl, $commentblock, $ifdef);
@@ -1026,7 +1032,7 @@ sub on_wrap_method_docs_only($)
   my $line_num = $$self{line_num};
 
   my $str = $self->extract_bracketed_text();
-  my @args = string_split_commas($str);
+  my @args = string_split_commas($str, 1);
 
   my $entity_type = "method";
 
@@ -1057,8 +1063,8 @@ sub on_wrap_method_docs_only($)
     }
   }
 
-  # Extra ref needed?
   $$objCfunc{throw_any_errors} = 0;
+  my $newin = "";
   while($#args >= 1) # If the optional ref/err arguments are there.
   {
     my $argRef = string_trim(pop @args);
@@ -1066,11 +1072,14 @@ sub on_wrap_method_docs_only($)
     {
       $$objCfunc{throw_any_errors} = 1;
     }
+    elsif($argRef =~ /^newin(.*)/) #If newin is at the start.
+    {
+      $newin = string_unquote(string_trim($1));
+    }
   }
 
   my $commentblock = "";
-  $commentblock = DocsParser::lookup_documentation($argCFunctionName, "");
-
+  $commentblock = DocsParser::lookup_documentation($argCFunctionName, "", $newin);
   $objOutputter->output_wrap_meth_docs_only($filename, $line_num, $commentblock);
 }
 
@@ -1227,6 +1236,7 @@ sub on_wrap_signal($$)
   my $ifdef;
   my $argDeprecated = "";
   my $deprecation_docs = "";
+  my $newin = "";
   my $exceptionHandler = "";
 
   while($#args >= 2) # If optional arguments are there.
@@ -1262,6 +1272,11 @@ sub on_wrap_signal($$)
       }
     }
 
+    elsif($argRef =~ /^newin(.*)/) #If newin is at the start.
+    {
+      $newin = string_unquote(string_trim($1));
+    }
+
     elsif($argRef =~ /^ifdef(.*)/) #If ifdef is at the start.
     {
     	$ifdef = $1;
@@ -1275,7 +1290,8 @@ sub on_wrap_signal($$)
 
   $self->output_wrap_signal($argCppDecl, $argCName, $$self{filename}, $$self{line_num},
                             $bCustomDefaultHandler, $bNoDefaultHandler, $bCustomCCallback,
-                            $bRefreturn, $ifdef, $commentblock, $argDeprecated, $deprecation_docs, $exceptionHandler);
+                            $bRefreturn, $ifdef, $commentblock, $argDeprecated, $deprecation_docs,
+                            $newin, $exceptionHandler);
 }
 
 # void on_wrap_vfunc()
@@ -1541,12 +1557,12 @@ sub output_wrap_check($$$$$$)
 
 # void output_wrap($CppDecl, $signal_name, $filename, $line_num, $bCustomDefaultHandler,
 #                  $bNoDefaultHandler, $bCustomCCallback, $bRefreturn, $ifdef,
-#                  $commentblock, $deprecated, $deprecation_docs, $exceptionHandler)
-sub output_wrap_signal($$$$$$$$$$$$)
+#                  $commentblock, $deprecated, $deprecation_docs, $newin, $exceptionHandler)
+sub output_wrap_signal($$$$$$$$$$$$$$)
 {
   my ($self, $CppDecl, $signal_name, $filename, $line_num, $bCustomDefaultHandler,
       $bNoDefaultHandler, $bCustomCCallback, $bRefreturn, $ifdef,
-      $commentblock, $deprecated, $deprecation_docs, $exceptionHandler) = @_;
+      $commentblock, $deprecated, $deprecation_docs, $newin, $exceptionHandler) = @_;
 
   #Some checks:
   return if ($self->output_wrap_check($CppDecl, $signal_name,
@@ -1580,7 +1596,7 @@ sub output_wrap_signal($$$$$$$$$$$$)
 
   $objOutputter->output_wrap_sig_decl($filename, $line_num, $objCSignal, $objCppSignal,
     $signal_name, $bCustomCCallback, $ifdef, $commentblock,
-    $deprecated, $deprecation_docs, $exceptionHandler);
+    $deprecated, $deprecation_docs, $newin, $exceptionHandler);
 
   if($bNoDefaultHandler eq 0)
   {