Hard Code Freeze break: glibmm deprecation docs

[Murray Cumming <murrayc murrayc com>]

This is technically a build fix, but it's not to fix a failure to build,
so I'm asking for permission to break the hard code freeze.

This patch allows me to improve our documentation. I've been using it
for a week or so, with no sign of problems. It's not urgent, but it's
very low risk, and I'd like to get it out of the way. I'd have done it
earlier, but I had connection problems for the past week.

-- 
Murray Cumming
murrayc murrayc com
www.murrayc.com
www.openismus.com

? glibmm_deprecated_docs.patch
? gtkmm-docs.tar.gz
? option.patch
? temp.patch
? examples/child_watch/child_watch
? examples/iochannel_stream/Makefile
? examples/iochannel_stream/Makefile.in
? examples/iochannel_stream/example
? examples/options/example
? glib/glibmm/optioncontext.cc
? glib/glibmm/optioncontext.h
? glib/glibmm/optionentry.cc
? glib/glibmm/optionentry.h
? glib/glibmm/optiongroup.cc
? glib/glibmm/optiongroup.h
? glib/glibmm/private/optioncontext_p.h
? glib/glibmm/private/optionentry_p.h
? glib/glibmm/private/optiongroup_p.h
? tools/gtk_enums.patch
Index: ChangeLog
===================================================================
RCS file: /cvs/gnome/glibmm/ChangeLog,v
retrieving revision 1.191
diff -u -p -r1.191 ChangeLog
--- ChangeLog	8 Mar 2006 12:22:57 -0000	1.191
+++ ChangeLog	8 Mar 2006 12:38:34 -0000
@@ -1,3 +1,21 @@
+2006-02-25  Murray Cumming  <murrayc murrayc com>
+ 
+	* tools/pm/DocsParser.pm: looklookup_documentation(): Put the 
+	@deprecated text immediately after the main description, before 
+	the parameters, so that Doxygen actually uses it.
+ 
+2006-02-25  Murray Cumming  <murrayc murrayc com>
+ 
+	* tools/pm/DocsParser.pm: looklookup_documentation(): Accept an 
+	extra deprecated_documentation parameter, to be appended to the 
+	Doxygen documentation.
+	* tools/pm/Output.pm: output_wrap_meth(): Put the documentation 
+	inside the deprecation #ifdef, for neatness.
+	* tools/pm/WrapParser.pm: on_wrap_method(): Read an optional string 
+	after the optional deprecated parameter, used to say why the 
+	method is deprecated, in case it was not deprecated by the C API, 
+	in which case it would already have documentation for this.
+
 2006-02-27  Cedric Gustin <cedric gustin gmail com>
 
 	* README.win32: Updated for glibmm-2.8 (MS Visual Studio 2005).
Index: tools/pm/DocsParser.pm
===================================================================
RCS file: /cvs/gnome/glibmm/tools/pm/DocsParser.pm,v
retrieving revision 1.5
diff -u -p -r1.5 DocsParser.pm
--- tools/pm/DocsParser.pm	30 Nov 2005 14:50:25 -0000	1.5
+++ tools/pm/DocsParser.pm	8 Mar 2006 12:38:34 -0000
@@ -232,38 +232,45 @@ sub parse_on_cdata($$)
 
 
 # $strCommentBlock lookup_documentation($strFunctionName)
-sub lookup_documentation($)
+sub lookup_documentation($$)
 {
-  my ($functionName) = @_;
-   
+  my ($functionName, $deprecation_docs) = @_;
+
   my $objFunction = $DocsParser::hasharrayFunctions{$functionName};
   if(!$objFunction)
   {
     #print "DocsParser.pm: Warning: function not found: $functionName\n";
     return ""
   }
-  
+
   my $text = $$objFunction{description};
 
   if(length($text) eq 0)
   {
     print "DocsParser.pm: Warning: No C docs for function: \"$functionName\"\n";
   }
-  
-      
+
+
   DocsParser::convert_docs_to_cpp($objFunction, \$text);
+
+  #Add note about deprecation if we have specified that in our _WRAP_METHOD() call:
+  if($deprecation_docs ne "")
+  {
+    $text .= "\n\ deprecated $deprecation_docs";
+  }
+
   DocsParser::append_parameter_docs($objFunction, \$text);
   DocsParser::append_return_docs($objFunction, \$text);
 
-    
+
   # Escape the space after "i.e." or "e.g." in the brief description.
   $text =~ s/^([^.]*\b(?:i\.e\.|e\.g\.))\s/$1\\ /;
-      
+
   # Convert to Doxygen-style comment.
   $text =~ s/\n/\n${DocsParser::commentMiddleStart}/g;
   $text =  $DocsParser::commentStart . $text;
   $text .= "\n${DocsParser::commentEnd}\n";
-      
+
   return $text;
 }
 
Index: tools/pm/Output.pm
===================================================================
RCS file: /cvs/gnome/glibmm/tools/pm/Output.pm,v
retrieving revision 1.14
diff -u -p -r1.14 Output.pm
--- tools/pm/Output.pm	29 Nov 2005 15:04:05 -0000	1.14
+++ tools/pm/Output.pm	8 Mar 2006 12:38:34 -0000
@@ -246,21 +246,22 @@ sub output_wrap_meth($$$$$$)
   my ($self, $filename, $line_num, $objCppfunc, $objCDefsFunc, $cppMethodDecl, $documentation) = @_;
   my $objDefsParser = $$self{objDefsParser};
 
-  # Doxygen documentation before the method declaration:
-  $self->output_wrap_meth_docs_only($filename, $line_num, $documentation);
-
-  # Allow the generated .h/.cc code to have an #ifndef around it.
+  # Allow the generated .h/.cc code to have an #ifndef around it, and add deprecation docs to the generated documentation.
   my $deprecated = "";
   if($$objCDefsFunc{deprecated})
   {
-    $deprecated = "errthrow"
+    $deprecated = "deprecated";
   }
 
   #Declaration:
   if($deprecated ne "")
   {
-    $self->append("_DEPRECATE_IFDEF_START\n");
+    $self->append("\n_DEPRECATE_IFDEF_START");
   }
+
+  # Doxygen documentation before the method declaration:
+  $self->output_wrap_meth_docs_only($filename, $line_num, $documentation);
+
 
   $self->append("  ${cppMethodDecl};");
 
Index: tools/pm/WrapParser.pm
===================================================================
RCS file: /cvs/gnome/glibmm/tools/pm/WrapParser.pm,v
retrieving revision 1.10
diff -u -p -r1.10 WrapParser.pm
--- tools/pm/WrapParser.pm	29 Nov 2005 15:04:05 -0000	1.10
+++ tools/pm/WrapParser.pm	8 Mar 2006 12:38:34 -0000
@@ -757,27 +757,33 @@ sub on_wrap_method($)
   }
 
   # Extra stuff needed?
+  $$objCfunc{deprecated} = "";
+  my $deprecation_docs = "";
   while(scalar(@args) > 2) # If the optional ref/err/deprecated arguments are there.
   {
     my $argRef = string_trim(pop @args);
+    #print "debug arg=$argRef\n";
     if($argRef eq "refreturn")
     {
       $$objCfunc{rettype_needs_ref} = 1;
     }
-    
-    if($argRef eq "errthrow")
+    elsif($argRef eq "errthrow")
     {
       $$objCfunc{throw_any_errors} = 1;
     }
-
-    if($argRef eq "deprecated")
+    elsif($argRef =~ /^deprecated(.*)/) #If deprecated is at the start.
     {
-      $$objCfunc{deprecated} = 1;
+      $$objCfunc{deprecated} = "deprecated";
+
+      if($1 ne "")
+      {
+        $deprecation_docs = string_unquote(string_trim($1));
+      }
     }
   }
-   
+
   my $commentblock = "";
-  $commentblock = DocsParser::lookup_documentation($argCFunctionName);
+  $commentblock = DocsParser::lookup_documentation($argCFunctionName, $deprecation_docs);
 
   $objOutputter->output_wrap_meth($filename, $line_num, $objCppfunc, $objCfunc, $argCppMethodDecl, $commentblock);
 }
@@ -814,7 +820,7 @@ sub on_wrap_method_docs_only($)
   $argCFunctionName = string_trim($argCFunctionName);
 
   #Get the c function's details:
-  
+
   #Checks that it's not empty and that it contains no whitespace.
   if ($argCFunctionName =~ /^\S+$/ ) 
   {
@@ -839,7 +845,7 @@ sub on_wrap_method_docs_only($)
   }
 
   my $commentblock = "";
-  $commentblock = DocsParser::lookup_documentation($argCFunctionName);
+  $commentblock = DocsParser::lookup_documentation($argCFunctionName, "");
 
   $objOutputter->output_wrap_meth_docs_only($filename, $line_num, $commentblock);
 }