gmmproc: Add documentation to wrapped signals.

	* tools/m4/signal.m4: Add docs to the on_*() default handlers
	referring the users to the signal_*() docs.
	* tools/pm/DocsParser.pm (parse_on_start):
	(parse_on_end): Allow the <signal></signal> tags from the generated
	XML docs to be processed in a similar way as the <function></function>
	tags are processed.  The docs of the signals are stored as
	"Class::a_signal_name" in the hash.
	(append_parameter_docs): Skip the first parameter for signals also
	because the first parameter of signals is the object for which the
	signal is triggered.
	(lookup_documentation): Generalize the no docs warning to include
	signals also.
	* tools/pm/Function.pm (get_refdoc_comment): Modify the subroutine to
	accept the docs of the signal (that the DocsParser stores) and include
	the prototype of the slot in the docs.
	* tools/pm/Output.pm (output_wrap_sig_decl): Modify the subroutine to
	look up the documentation of the signal which it then passes to
	get_refdoc_comment() so that the documentation of the signal from the
	generated XML is included in the declaration of the signal.

	Bug #668918 (Mark)

7 files changed, 75 insertions, 15 deletions

diff --git a/ChangeLog b/ChangeLog
index 6bc15810..ca593856 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,29 @@
+2012-02-03  José Alburquerque  <jaalburquerque@gmail.com>
+
+	gmmproc: Add documentation to wrapped signals.
+
+	* tools/m4/signal.m4: Add docs to the on_*() default handlers
+	referring the users to the signal_*() docs.
+	* tools/pm/DocsParser.pm (parse_on_start):
+	(parse_on_end): Allow the <signal></signal> tags from the generated
+	XML docs to be processed in a similar way as the <function></function>
+	tags are processed.  The docs of the signals are stored as
+	"Class::a_signal_name" in the hash.
+	(append_parameter_docs): Skip the first parameter for signals also
+	because the first parameter of signals is the object for which the
+	signal is triggered.
+	(lookup_documentation): Generalize the no docs warning to include
+	signals also.
+	* tools/pm/Function.pm (get_refdoc_comment): Modify the subroutine to
+	accept the docs of the signal (that the DocsParser stores) and include
+	the prototype of the slot in the docs.
+	* tools/pm/Output.pm (output_wrap_sig_decl): Modify the subroutine to
+	look up the documentation of the signal which it then passes to
+	get_refdoc_comment() so that the documentation of the signal from the
+	generated XML is included in the declaration of the signal.
+
+	Bug #668918 (Mark)
+
 2.31.16:
 
 2012-01-30  TS  <t.sailer@alumni.ethz.ch>
diff --git a/tools/m4/signal.m4 b/tools/m4/signal.m4
index 970c20db..9cf43052 100644
--- a/tools/m4/signal.m4
+++ b/tools/m4/signal.m4
@@ -230,6 +230,7 @@ define(`_SIGNAL_H',`dnl
 _PUSH(SECTION_H_DEFAULT_SIGNAL_HANDLERS)
 ifelse(`$4',,,`#ifdef $4'
 )dnl
+  /// This is a default handler for the signal signal_$1`'().
   virtual $2 on_$1`'($3);
 ifelse(`$4',,,`#endif // $4
 ')dnl
diff --git a/tools/pm/DocsParser.pm b/tools/pm/DocsParser.pm
index aa46cdca..7df773b6 100644
--- a/tools/pm/DocsParser.pm
+++ b/tools/pm/DocsParser.pm
@@ -112,7 +112,7 @@ sub parse_on_start($$%)
 
   $tag = lc($tag);
 
-  if($tag eq "function")
+  if($tag eq "function" or $tag eq "signal")
   {
     if(defined $DocsParser::objCurrentFunction)
     {
@@ -121,6 +121,9 @@ sub parse_on_start($$%)
 
     my $functionName = $attr{name};
 
+    # Change signal name from Class::a-signal-name to Class::a_signal_name.
+    $functionName =~ s/-/_/g if($tag eq "signal");
+
     #Reuse existing Function, if it exists:
     #(For instance, if this is the override parse)
     $DocsParser::objCurrentFunction = $DocsParser::hasharrayFunctions{$functionName};
@@ -191,7 +194,7 @@ sub parse_on_end($$)
 
   $tag = lc($tag);
 
-  if($tag eq "function")
+  if($tag eq "function" or $tag eq "signal")
   {
     # Store the Function structure in the array:
     my $functionName = $$DocsParser::objCurrentFunction{name};
@@ -246,7 +249,7 @@ sub lookup_documentation($$)
 
   if(length($text) eq 0)
   {
-    print "DocsParser.pm: Warning: No C docs for function: \"$functionName\"\n";
+    print "DocsParser.pm: Warning: No C docs for: \"$functionName\"\n";
   }
 
   DocsParser::convert_docs_to_cpp($objFunction, \$text);
@@ -266,10 +269,10 @@ sub lookup_documentation($$)
 
   # Remove C example code.
   my $example_removals =
-    ($text =~ s"<informalexample>.*?</informalexample>""sg);
+    ($text =~ s"<informalexample>.*?</informalexample>"\[C example ellipted]"sg);
   $example_removals +=
-    ($text =~ s"<programlisting>.*?</programlisting>""sg);
-  $example_removals += ($text =~ s"\|\[.*?]\|""sg);
+    ($text =~ s"<programlisting>.*?</programlisting>"\n[C example ellipted]"sg);
+  $example_removals += ($text =~ s"\|\[.*?]\|"\n[C example ellipted]"sg);
 
   print STDERR "gmmproc: $functionName(): Example code discarded.\n"
     if ($example_removals);
@@ -311,6 +314,9 @@ sub append_parameter_docs($$)
   shift(@param_names) if(($defs_method && $$defs_method{class} ne "") ||
                          ($$obj_function{mapped_class} ne ""));
 
+  # Also skip first param if this is a signal.
+  shift(@param_names) if ($$obj_function{name} =~ /\w+::/);
+
   foreach my $param (@param_names)
   {
     if ($param ne "error" ) #We wrap GErrors as exceptions, so ignore these.
diff --git a/tools/pm/Function.pm b/tools/pm/Function.pm
index 8032c047..7073ebe0 100644
--- a/tools/pm/Function.pm
+++ b/tools/pm/Function.pm
@@ -376,15 +376,16 @@ sub add_parameter($$$)
   return $self;
 }
 
-# $string get_refdoc_comment()
-# Generate a readable prototype for signals.
-sub get_refdoc_comment($)
+# $string get_refdoc_comment($existing_signal_docs)
+# Generate a readable prototype for signals and merge the prototype into the
+# existing Doxygen comment block.
+sub get_refdoc_comment($$)
 {
-  my ($self) = @_;
+  my ($self, $documentation) = @_;
 
   my $str = "  /**\n";
 
-  $str .= "   * \@par Prototype:\n";
+  $str .= "   * \@par Slot Prototype:\n";
   $str .= "   * <tt>$$self{rettype} on_my_\%$$self{name}(";
 
   my $param_names = $$self{param_names};
@@ -399,8 +400,21 @@ sub get_refdoc_comment($)
   }
 
   $str .= ")</tt>\n";
-  $str .= "   */";
+  $str .= "   *\n";
+
+  if($documentation ne "")
+  {
+    # Remove the initial '/** ' from the existing docs and merge it.
+    $documentation =~ s/\/\*\*\s+/ \* /;
+    $str .= $documentation;
+  }
+  else
+  {
+    # Close the doc block if there's no existing docs.
+    $str .= "   */\n";
+  }
 
+  # Return the merged documentation.
   return $str;
 }
 
diff --git a/tools/pm/Output.pm b/tools/pm/Output.pm
index 4ec437d9..79a5e40a 100644
--- a/tools/pm/Output.pm
+++ b/tools/pm/Output.pm
@@ -20,6 +20,8 @@ package Output;
 use strict;
 use open IO => ":utf8";
 
+use DocsParser;
+
 BEGIN { @Namespace::ISA=qw(main); }
 
 # $objOutputter new()
@@ -481,7 +483,18 @@ sub output_wrap_sig_decl($$$$$$$$)
 #               cpp_signal_name, cpp_return_type, `<cpp_arg_types>',`<c_args_to_cpp>',
 #               refdoc_comment)
 
-  my $doxycomment = $objCppfunc->get_refdoc_comment();
+  # Get the signal name with underscores only (to look up docs -- they are
+  # stored that way).
+  my $underscored_signal_name = $signal_name;
+  $underscored_signal_name =~ s/-/_/g;
+
+  # Get the existing signal documentation from the parsed docs.
+  my $documentation =
+    DocsParser::lookup_documentation("$$objCSignal{class}::$underscored_signal_name", "");
+
+  # 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).
+  my $doxycomment = $objCppfunc->get_refdoc_comment($documentation);
 
   # If there was already a previous doxygen comment, we want to merge this
   # one with the previous so it is one big comment. If it were two separate
diff --git a/tools/pm/Util.pm b/tools/pm/Util.pm
index cc1ccfa0..f8bc9331 100644
--- a/tools/pm/Util.pm
+++ b/tools/pm/Util.pm
@@ -51,7 +51,7 @@ sub string_unquote($)
 
     $str =~ s/^['`"]// ;
     $str =~ s/['`"]$// ;
- 
+
     return $str;
 }
 
diff --git a/tools/pm/WrapParser.pm b/tools/pm/WrapParser.pm
index 04abd0f1..d2716222 100644
--- a/tools/pm/WrapParser.pm
+++ b/tools/pm/WrapParser.pm
@@ -1414,7 +1414,7 @@ sub byattrib()
      "sig_decl"     ,4, 
      "meth"         ,5
   );
- 
+
   # $a and $b are hidden parameters to a sorting function
   return $attrib_value{$b} <=> $attrib_value{$a}; 
 }