Re: Setting a RadioItem created with ItemFactory

[Emmanuele Bassi <ebassi gmail com>]

On Thu, 2007-01-04 at 21:44 +0000, Emmanuele Bassi wrote:

> > Ah. Didn't know that. I'll add switching to the UIManager to the to do
> > list. Is there any chance of getting this added to the POD? The same
> > applies to FileChooser and FileSelector and I'm sure others too.
> 
> hmm.  we should really add a marker in the apidoc generator for
> deprecated objects.

which is what I just did: now, a deprecated module should add:

  =for deprecated_for Foo::Bar
  =cut

and the autogenerated api documentation should have a nice deprecation
warning telling you what you need to look at.  alas, migration guides
still need to be written by hand, but at least you should have an idea
where to look.

the first patch implements the marker; the second adds it to the
deprecated widgets:

  Gtk2::Combo, deprecated for Gtk2::ComboBox
  Gtk2::FileSelection, deprecated for Gtk2::FileChooserDialog
  Gtk2::ItemFactory, deprecated for Gtk2::UIManager
  Gtk2::OptionMenu, deprecated for Gtk2::ComboBox

the first patch also adds a __deprecated__ marker for functions and
methods, working like the __hidden__ and __gerror__ markers; it'll add a
deprecation warning on single functions and methods.

if nobody has objections or suggestions, I'll commit them both.

ciao,
 Emmanuele.

-- 
Emmanuele Bassi,  E: ebassi gmail com
W: http://www.emmanuelebassi.net
B: http://log.emmanuelebassi.net

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__/);
 			}
 		}

Index: ChangeLog
===================================================================
RCS file: /cvsroot/gtk2-perl/gtk2-perl-xs/Gtk2/ChangeLog,v
retrieving revision 1.732
diff -p -a -u -r1.732 ChangeLog
--- ChangeLog	30 Dec 2006 15:40:58 -0000	1.732
+++ ChangeLog	4 Jan 2007 22:49:46 -0000
@@ -1,3 +1,10 @@
+2007-01-04  Emmanuele Bassi  <ebassi gnome org>
+
+	* xs/GtkCombo.xs:
+	* xs/GtkFileSelection.xs:
+	* xs/GtkItemFactory.xs:
+	* xs/GtkOptionMenu.xs: Add deprecation warnings.
+
 2006-12-30	kaffeetisch
 
 	* GtkTreeSortable.xs: Don't segfault in the GET_SORT_COLUMN_ID
Index: xs/GtkCombo.xs
===================================================================
RCS file: /cvsroot/gtk2-perl/gtk2-perl-xs/Gtk2/xs/GtkCombo.xs,v
retrieving revision 1.15
diff -p -a -u -r1.15 GtkCombo.xs
--- xs/GtkCombo.xs	26 Feb 2004 00:57:54 -0000	1.15
+++ xs/GtkCombo.xs	4 Jan 2007 22:49:46 -0000
@@ -23,6 +23,9 @@
 
 MODULE = Gtk2::Combo	PACKAGE = Gtk2::Combo	PREFIX = gtk_combo_
 
+=for deprecated_for Gtk2::ComboBox
+=cut
+
 ## GtkWidget* gtk_combo_new (void)
 GtkWidget*
 gtk_combo_new (class)
Index: xs/GtkFileSelection.xs
===================================================================
RCS file: /cvsroot/gtk2-perl/gtk2-perl-xs/Gtk2/xs/GtkFileSelection.xs,v
retrieving revision 1.16
diff -p -a -u -r1.16 GtkFileSelection.xs
--- xs/GtkFileSelection.xs	26 Feb 2004 00:57:54 -0000	1.16
+++ xs/GtkFileSelection.xs	4 Jan 2007 22:49:46 -0000
@@ -23,6 +23,9 @@
 
 MODULE = Gtk2::FileSelection	PACKAGE = Gtk2::FileSelection	PREFIX = gtk_file_selection_
 
+=for deprecated_for Gtk2::FileChooserDialog
+=cut
+
 GtkWidget *
 dir_list (fs)
 	GtkFileSelection* fs
Index: xs/GtkItemFactory.xs
===================================================================
RCS file: /cvsroot/gtk2-perl/gtk2-perl-xs/Gtk2/xs/GtkItemFactory.xs,v
retrieving revision 1.21
diff -p -a -u -r1.21 GtkItemFactory.xs
--- xs/GtkItemFactory.xs	6 Jan 2005 04:19:50 -0000	1.21
+++ xs/GtkItemFactory.xs	4 Jan 2007 22:49:46 -0000
@@ -231,6 +231,8 @@ gtk2perl_item_factory_create_item_helper
 
 MODULE = Gtk2::ItemFactory	PACKAGE = Gtk2::ItemFactory	PREFIX = gtk_item_factory_
 
+=for deprecated_for Gtk2::UIManager
+=cut
 
 ##  GtkItemFactory* gtk_item_factory_new (GType container_type, const gchar *path, GtkAccelGroup *accel_group) 
 GtkItemFactory*
Index: xs/GtkOptionMenu.xs
===================================================================
RCS file: /cvsroot/gtk2-perl/gtk2-perl-xs/Gtk2/xs/GtkOptionMenu.xs,v
retrieving revision 1.6
diff -p -a -u -r1.6 GtkOptionMenu.xs
--- xs/GtkOptionMenu.xs	12 Oct 2003 17:57:30 -0000	1.6
+++ xs/GtkOptionMenu.xs	4 Jan 2007 22:49:46 -0000
@@ -23,6 +23,9 @@
 
 MODULE = Gtk2::OptionMenu	PACKAGE = Gtk2::OptionMenu	PREFIX = gtk_option_menu_
 
+=for deprecated_for Gtk2::ComboBox
+=cut
+
 GtkWidget *
 gtk_option_menu_new (class)
     C_ARGS: