looklookup_documentation(): Put the @deprecated text immediately after the

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.

6 files changed, 73 insertions, 27 deletions

diff --git a/ChangeLog b/ChangeLog
index 20672338..854b5bc3 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,23 @@
+2.10.0:
+
+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).
diff --git a/NEWS b/NEWS
index b43ef8a4..2deda6b4 100644
--- a/NEWS
+++ b/NEWS
@@ -1,3 +1,15 @@
+2.10.0:
+
+* Windows Build:
+ - ustring.h: Tag npos with GLIBMM_API, in order to
+   dllexport it on win32. Bug #332438.
+ - Updated MSVC++ build files and README, for MS Visual Studio 2005.
+ (Cedric Gustin)
+* gmmproc code generator: 
+ - WRAP_METHOD() Take an extra optional argument: deprecated deprecationtext - 
+  so that we can insert the appropriate doxygen tag in the documentation, where 
+  the C documentation does not do it for us.
+
 2.9.1:
 
 * Date:
diff --git a/configure.in b/configure.in
index b7afdf04..ae8d7fc7 100644
--- a/configure.in
+++ b/configure.in
@@ -18,8 +18,8 @@ AC_PREREQ(2.50)
 #  Version and initialization
 #########################################################################
 GLIBMM_MAJOR_VERSION=2
-GLIBMM_MINOR_VERSION=9
-GLIBMM_MICRO_VERSION=1
+GLIBMM_MINOR_VERSION=10
+GLIBMM_MICRO_VERSION=0
 GLIBMM_VERSION=$GLIBMM_MAJOR_VERSION.$GLIBMM_MINOR_VERSION.$GLIBMM_MICRO_VERSION
 GLIBMM_RELEASE=$GLIBMM_MAJOR_VERSION.$GLIBMM_MINOR_VERSION
 AC_DEFINE_UNQUOTED(GLIBMM_MAJOR_VERSION, $GLIBMM_MAJOR_VERSION)
@@ -38,7 +38,7 @@ AC_SUBST(GLIBMM_RELEASE)
 #  ? :+1 : ?   == just some internal changes, nothing breaks but might work 
 #                 better
 # CURRENT : REVISION : AGE
-LIBGLIBMM_SO_VERSION=1:20:0
+LIBGLIBMM_SO_VERSION=1:21:0
 AC_SUBST(LIBGLIBMM_SO_VERSION)
 
 AC_CONFIG_AUX_DIR(scripts)
diff --git a/tools/pm/DocsParser.pm b/tools/pm/DocsParser.pm
index ef1f8be3..62ff6e71 100644
--- a/tools/pm/DocsParser.pm
+++ b/tools/pm/DocsParser.pm
@@ -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;
 }
 
diff --git a/tools/pm/Output.pm b/tools/pm/Output.pm
index 2000ff5f..5d805fc1 100644
--- a/tools/pm/Output.pm
+++ b/tools/pm/Output.pm
@@ -246,22 +246,23 @@ 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};");
 
   if($deprecated ne "")
diff --git a/tools/pm/WrapParser.pm b/tools/pm/WrapParser.pm
index 924d3a8e..2dd296dd 100644
--- a/tools/pm/WrapParser.pm
+++ b/tools/pm/WrapParser.pm
@@ -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);
 }