Index: ChangeLog
===================================================================
RCS file: /cvsroot/gtk2-perl/gtk2-perl-xs/Glib/ChangeLog,v
retrieving revision 1.409
diff -p -a -u -r1.409 ChangeLog
--- ChangeLog	30 Dec 2006 15:37:17 -0000	1.409
+++ ChangeLog	4 Jan 2007 23:02:35 -0000
@@ -1,3 +1,11 @@
+2007-01-04  Emmanuele Bassi  <ebassi gnome org>
+
+	* ParseXSDoc.pm:
+	* GenPod.pm: Add a "deprecated_for" key to the apidoc parser;
+	you should use this to mark an object deprecated in favour of
+	another.  Also add a __deprecated__ marker for functions and
+	methods, adding a deprecation warning.
+
 2006-12-30	kaffeetisch
 
 	* Glib.xs: Call g_threads_init before g_type_init.  Required (and
Index: GenPod.pm
===================================================================
RCS file: /cvsroot/gtk2-perl/gtk2-perl-xs/Glib/GenPod.pm,v
retrieving revision 1.60
diff -p -a -u -r1.60 GenPod.pm
--- GenPod.pm	3 Oct 2006 15:43:19 -0000	1.60
+++ GenPod.pm	4 Jan 2007 23:02:35 -0000
@@ -32,6 +32,7 @@ our @EXPORT = qw(
 	podify_interfaces
 	podify_methods
 	podify_enums_and_flags
+    podify_deprecated_for
 );
 
 our $COPYRIGHT = undef;
@@ -105,6 +106,12 @@ writing the pod for the current package 
 MODULE line).  Any text in this paragraph, to the next C<=cut>, is included
 in that section.
 
+=item =for deprecated_for Package::Name
+
+Used to add a deprecation warning, indicating I<Package::Name> as an
+alternative way to achieve the same functionality.  There may be any number
+these in each package.
+
 =item =for see_also L<some_thing_to_see>
 
 Used to add extra see alsos onto the end of the parents, if any, for a given
@@ -179,6 +186,11 @@ This function or method can generate a G
 Generate a function-style signature for this xsub.  The default is to
 generate method-style signatures.
 
+=item - __deprecated__
+
+This function or method is deprecated and should not be used in newly written
+code.
+
 =back
 
 (These are actually handled by Glib::ParseXSDoc, but we list them here
@@ -297,6 +309,9 @@ sub xsdoc2pod
 		$ret = podify_pods ($pkgdata->{pods}, 'post_enums');
 		print "$ret\n\n" if ($ret);
 
+        $ret = podify_deprecated_for ($package, @{ $pkgdata->{deprecated_for} });
+        print "\n=head1 DEPRECATION WARNING\n\n$ret" if ($ret);
+
 		$ret = podify_pods ($pkgdata->{pods}, 'SEE_ALSO');
 		if ($ret)
 		{
@@ -533,6 +548,38 @@ sub podify_signals {
     return $str
 }
 
+=item $string = podify_deprecated_for ($packagename, @deprecated_for)
+
+Creates a deprecation warning for $packagename, suggesting using the items
+inside @deprecated_for instead.
+
+=cut
+
+sub podify_deprecated_for
+{
+    my $package        = shift;
+    my @deprecated_for = @_;
+
+    my $str = "$package has been marked as deprecated, and should not be "
+            . "used in newly written code.\n\n";
+
+    return $str unless scalar @deprecated_for;
+
+	# create the deprecated for list
+	$str .= "You should use "
+         . join (', ',
+                 map {
+                     if (/^\s*L</) {
+                        $_;
+                     } else {
+                        "L<$_>";
+                     }
+		         } @deprecated_for)
+	     . " instead of $package.\n";
+
+    return $str;
+}
+
 sub podify_enums_and_flags
 {
 	my $pkgdata = shift;
@@ -1139,6 +1186,9 @@ sub xsub_to_pod {
 	$str .= "May croak with a L<Glib::Error> in \$@ on failure.\n\n"
 		if ($xsub->{gerror});
 
+    $str .= "This method is deprecated and should not be used in newly written code.\n\n"
+        if ($xsub->{deprecated});
+
 	$str .= "=back\n\n";
 
 	$str
Index: ParseXSDoc.pm
===================================================================
RCS file: /cvsroot/gtk2-perl/gtk2-perl-xs/Glib/ParseXSDoc.pm,v
retrieving revision 1.29
diff -p -a -u -r1.29 ParseXSDoc.pm
--- ParseXSDoc.pm	3 Oct 2006 15:43:19 -0000	1.29
+++ ParseXSDoc.pm	4 Jan 2007 23:02:35 -0000
@@ -316,7 +316,10 @@ sub parse_file {
 				push @{ $self->pkgdata->{see_alsos} }, $1;
 				# claim this pod now!
 				$lastpod = undef;
-			}
+			} elsif (/^=for\s+deprecated_for\s+([\w:]+)$/) {
+                push @{ $self->pkgdata->{deprecated_for} }, $1;
+                $lastpod = undef;
+            }
 			push @{ $self->pkgdata->{pods} }, $lastpod
 				if defined $lastpod;
 
@@ -423,6 +426,7 @@ sub preprocess_pods {
 			if ($firstline) {
 				$_->{function} = ($firstline =~ /__function__/);
 				$_->{hidden} = ($firstline =~ /__hide__/);
+                $_->{deprecated} = ($firstline =~ /__deprecated__/);
 				$_->{gerror} = ($firstline =~ /__gerror__/);
 			}
 		}