[glibmm] Allow the C documentation to be overridden

[Daniel Elstner <daniel src gnome org>]

commit d7f026e8a9893c5446e1f90fa32962273252106d
Author: Daniel Elstner <danielk openismus com>
Date:   Thu Sep 10 22:16:46 2009 +0200

    Allow the C documentation to be overridden
    
    * tools/pm/WrapParser.pm (extract_preceding_documentation): Factor
    the code from on_wrap_enum() to extract a preceding comment block
    into a separate subroutine.
    (on_wrap_method): Invoke extract_preceding_documentation() to
    extract a preceding Doxygen comment, and if one was found allow
    it to override the inherited C documentation.

 ChangeLog              |   11 ++++++
 tools/pm/WrapParser.pm |   81 ++++++++++++++++++++++++++++--------------------
 2 files changed, 58 insertions(+), 34 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 6415bfa..a131026 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,16 @@
 2009-09-10  Daniel Elstner  <danielk openismus com>
 
+	Allow the C documentation to be overridden
+
+	* tools/pm/WrapParser.pm (extract_preceding_documentation): Factor
+	the code from on_wrap_enum() to extract a preceding comment block
+	into a separate subroutine.
+	(on_wrap_method): Invoke extract_preceding_documentation() to
+	extract a preceding Doxygen comment, and if one was found allow
+	it to override the inherited C documentation.
+
+2009-09-10  Daniel Elstner  <danielk openismus com>
+
 	Fix broken test for empty _WRAP_METHOD argument
 
 	* tools/pm/DocsParser.pm: Escape variable values substituted into
diff --git a/tools/pm/WrapParser.pm b/tools/pm/WrapParser.pm
index dacdb90..cebb294 100644
--- a/tools/pm/WrapParser.pm
+++ b/tools/pm/WrapParser.pm
@@ -799,6 +799,41 @@ sub check_for_eof($)
   return 1; # No EOF
 }
 
+# Look back for a Doxygen comment.  If there is one,
+# remove it from the output and return it as a string.
+sub extract_preceding_documentation ($)
+{
+  my ($self) = @_;
+  my $outputter = $$self{objOutputter};
+  my $out = \ {$$outputter{out}};
+
+  my $comment = '';
+
+  if ($#$out >= 2)
+  {
+    # steal the last three tokens
+    my @back = splice(@$out, -3);
+    local $_ = join('', @back);
+
+    # Check for /*[*!] ... */ or //[/!] comments.  The closing */ _must_
+    # be the last token of the previous line.  Apart from this restriction,
+    # anything else should work, including multi-line comments.
+
+    if (m#\A/\s*\*(?:\*`|`!)(.+)'\*/\s*\z#s or m#\A\s*//`[/!](.+)'\s*\z#s)
+    {
+      $comment = $1;
+      $comment =~ s/\s+$//;
+    }
+    else
+    {
+      # restore stolen tokens
+      push(@$out, @back);
+    }
+  }
+
+  return $comment;
+}
+
 # void on_wrap_method()
 sub on_wrap_method($)
 {
@@ -810,6 +845,7 @@ sub on_wrap_method($)
   my $filename = $$self{filename};
   my $line_num = $$self{line_num};
 
+  my $commentblock = $self->extract_preceding_documentation();
   my $str = $self->extract_bracketed_text();
   my @args = string_split_commas($str);
 
@@ -890,8 +926,14 @@ sub on_wrap_method($)
     }
   }
 
-  my $commentblock = "";
-  $commentblock = DocsParser::lookup_documentation($argCFunctionName, $deprecation_docs);
+  if ($commentblock ne '')
+  {
+    $commentblock = '  /**' . $commentblock . "\n   */\n";
+  }
+  else
+  {
+    $commentblock = DocsParser::lookup_documentation($argCFunctionName, $deprecation_docs);
+  }
 
   $objOutputter->output_wrap_meth($filename, $line_num, $objCppfunc, $objCfunc, $argCppMethodDecl, $commentblock, $ifdef);
 }
@@ -902,10 +944,7 @@ sub on_wrap_method_docs_only($)
   my ($self) = @_;
   my $objOutputter = $$self{objOutputter};
 
-  if( !($self->check_for_eof()) )
-  {
-   return;
-  }
+  return unless ($self->check_for_eof());
 
   my $filename = $$self{filename};
   my $line_num = $$self{line_num};
@@ -1165,36 +1204,10 @@ sub on_wrap_enum($)
 {
   my ($self) = @_;
 
-  return if(!$self->check_for_eof());
+  return unless ($self->check_for_eof());
 
   my $outputter = $$self{objOutputter};
-  my $out = \ {$$outputter{out}};
-
-  # Look back for a Doxygen comment for this _WRAP_ENUM.  If there is one,
-  # remove it from the output and pass it to the m4 _ENUM macro instead.
-  my $comment = "";
-
-  if($#$out > 0)
-  {
-    # steal the last two tokens
-    my @back = splice(@$out, -2);
-    local $_ = $back[0];
-
-    # Check for /*[*!] ... */ or //[/!] comments.  The closing */ _must_
-    # be the last token of the previous line.  Apart from this restriction,
-    # anything else should work, including multi-line comments.
-
-    if($back[1] eq "\n" && (m#^/\*`[*!](.+)'\*/#s || m#^//`[/!](.+)'$#))
-    {
-      $comment = $1;
-      $comment =~ s/\s+$//;
-    }
-    else
-    {
-      # restore stolen tokens
-      push(@$out, @back);
-    }
-  }
+  my $comment = $self->extract_preceding_documentation();
 
   # get the arguments
   my @args = string_split_commas($self->extract_bracketed_text());