[glibmm] gmmproc: Documentation: Adjust if the method has a slot param.

[Josà Alburquerque <jaalburqu src gnome org>]

commit eebb845eea977aa2f777c0c83c90306d79798ce8
Author: Josà Alburquerque <jaalburqu svn gnome org>
Date:   Mon Nov 19 11:25:36 2012 -0500

    gmmproc: Documentation: Adjust if the method has a slot param.
    
    	* tools/pm/WrapParser.pm (on_wrap_method): Pass the objCppfunc object
    	to the DocParser::lookup_documentation() subroutine so that it can
    	decide if the final parameter of the C function should be excluded
    	from the docs.  The final parameter (which would be a gpointer
    	user_data parameter) would be omitted if the C++ method has a slot
    	parameter.
    	* tools/pm/DocsParser.pm (lookup_documentation): Pass the objCppfunc
    	on to the append_parameter_docs() subroutine which does what's
    	described above.
    	(append_parameter_documentation): Decide whether to skip the final C
    	parameter as described above.  Also rename 'callback' parameters to
    	'slot' and use '@a slot' instead of '@a callback' in the main
    	description.
    	(substitute_identifiers): Replace C *Callback types to C++ Slot*
    	types.
    
    	Bug #688587.

 ChangeLog              |   22 ++++++++++++++++++++++
 tools/pm/DocsParser.pm |   33 +++++++++++++++++++++++++++------
 tools/pm/WrapParser.pm |    3 ++-
 3 files changed, 51 insertions(+), 7 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index d715ea5..e932ca0 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,27 @@
 2012-11-18  Josà Alburquerque  <jaalburquerque gmail com>
 
+	gmmproc: Documentation: Adjust if the method has a slot param.
+
+	* tools/pm/WrapParser.pm (on_wrap_method): Pass the objCppfunc object
+	to the DocParser::lookup_documentation() subroutine so that it can
+	decide if the final parameter of the C function should be excluded
+	from the docs.  The final parameter (which would be a gpointer
+	user_data parameter) would be omitted if the C++ method has a slot
+	parameter.
+	* tools/pm/DocsParser.pm (lookup_documentation): Pass the objCppfunc
+	on to the append_parameter_docs() subroutine which does what's
+	described above.
+	(append_parameter_documentation): Decide whether to skip the final C
+	parameter as described above.  Also rename 'callback' parameters to
+	'slot' and use '@a slot' instead of '@a callback' in the main
+	description.
+	(substitute_identifiers): Replace C *Callback types to C++ Slot*
+	types.
+
+	Bug #688587.
+
+2012-11-18  Josà Alburquerque  <jaalburquerque gmail com>
+
 	gmmproc: _WRAP_METHOD: Support wrapping methods with slots.
 
 	* tools/pm/WrapParser.pm (on_wrap_method): Add code to parse the
diff --git a/tools/pm/DocsParser.pm b/tools/pm/DocsParser.pm
index 6379981..c9436bb 100644
--- a/tools/pm/DocsParser.pm
+++ b/tools/pm/DocsParser.pm
@@ -305,10 +305,13 @@ sub lookup_enum_value_documentation($$)
   return $desc;
 }
 
-# $strCommentBlock lookup_documentation($strFunctionName, $deprecation_docs)
-sub lookup_documentation($$)
+# $strCommentBlock lookup_documentation($strFunctionName, $deprecation_docs, $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($$;$)
 {
-  my ($functionName, $deprecation_docs) = @_;
+  my ($functionName, $deprecation_docs, $objCppfunc) = @_;
 
   my $objFunction = $DocsParser::hasharrayFunctions{$functionName};
   if(!$objFunction)
@@ -332,7 +335,7 @@ sub lookup_documentation($$)
     $text .= "\n\ deprecated $deprecation_docs";
   }
 
-  DocsParser::append_parameter_docs($objFunction, \$text);
+  DocsParser::append_parameter_docs($objFunction, \$text, $objCppfunc);
   DocsParser::append_return_docs($objFunction, \$text);
   DocsParser::add_m4_quotes(\$text);
 
@@ -381,9 +384,12 @@ sub add_m4_quotes($)
   $$text = "`" . $$text . "'";
 }
 
-sub append_parameter_docs($$)
+# The final objCppfunc is optional.  If passed, it is used to determine
+# if the final C parameter should be omitted if the C++ method has a
+# slot parameter.
+sub append_parameter_docs($$;$)
 {
-  my ($obj_function, $text) = @_;
+  my ($obj_function, $text, $objCppfunc) = @_;
 
   my @param_names = @{$$obj_function{param_names}};
   my $param_descriptions = \$$obj_function{param_descriptions};
@@ -398,12 +404,24 @@ sub append_parameter_docs($$)
   # Also skip first param if this is a signal.
   shift(@param_names) if ($$obj_function{name} =~ /\w+::/);
 
+  # Skip the last param if there is a slot because it would be a
+  # gpointer user_data parameter.
+  pop(@param_names) if (defined($objCppfunc) && $$objCppfunc{slot_name});
+
   foreach my $param (@param_names)
   {
     if ($param ne "error" ) #We wrap GErrors as exceptions, so ignore these.
     {
       my $desc = $$param_descriptions->{$param};
 
+      # Deal with callback parameters converting the docs to a slot
+      # compatible format.
+      if ($param eq "callback")
+      {
+        $param = "slot";
+        $$text =~ s/\ a callback/\ a slot/g;
+      }
+
       $param =~ s/([a-zA-Z0-9]*(_[a-zA-Z0-9]+)*)_?/$1/g;
       DocsParser::convert_docs_to_cpp($obj_function, \$desc);
       if(length($desc) > 0)
@@ -544,6 +562,9 @@ sub substitute_identifiers($$)
     s/\bNo::/NO_/g;
     s/\bG:://g; #Rename G::Something to Something. Doesn't seem to work. murrayc.
 
+    # Substitute callback types to slot types.
+    s/(\b\w+)Callback/Slot$1/g;
+
     # Replace C function names with C++ counterparts.
     s/\b([a-z]+_[a-z][a-z\d_]+) ?\(\)/&DocsParser::substitute_function($doc_func, $1)/eg;
   }
diff --git a/tools/pm/WrapParser.pm b/tools/pm/WrapParser.pm
index f538b96..82c148f 100644
--- a/tools/pm/WrapParser.pm
+++ b/tools/pm/WrapParser.pm
@@ -969,7 +969,8 @@ sub on_wrap_method($)
   }
   else
   {
-    $commentblock = DocsParser::lookup_documentation($argCFunctionName, $deprecation_docs);
+    $commentblock = DocsParser::lookup_documentation($argCFunctionName,
+      $deprecation_docs, $objCppfunc);
   }
 
   $objOutputter->output_wrap_meth($filename, $line_num, $objCppfunc, $objCfunc, $argCppMethodDecl, $commentblock, $ifdef);