my $class = shift;
my %args = @_;
+ $args{-api_version} ||= delete $args{-compatible};
+
$registry->{ caller() } = $args{-api_version}
if $args{-api_version};
=head1 SYNOPSIS
- ...
+ package My::Class;
+
+ use Package::DeprecationManager
+ -deprecations => {
+ 'My::Class::foo' => '0.02',
+ 'My::Class::bar' => '0.05',
+ };
+
+ sub foo {
+ deprecated( 'Do not call foo!' );
+
+ ...
+ }
+
+ sub bar {
+ deprecated();
+
+ ...
+ }
+
+ package Other::Class;
+
+ use My::Class -api_version => '0.04';
+
+ My::Class->new()->foo(); # warns
+ My::Class->new()->bar(); # does not warn
+ My::Class->new()->far(); # does not warn again
=head1 DESCRIPTION
+This module allows you to manage a set of deprecations for one or more modules.
+
+When you import C<Package::DeprecationManager>, you must provide a set of
+C<-deprecations> as a hash ref. The keys are fully qualified sub/method names,
+and the values are the version when that subroutine was deprecated.
+
+As part of the import process, C<Package::DeprecationManager> will export two
+subroutines into its caller. It proves an C<import()> sub for the caller and a
+C<deprecated()> sub.
+
+The C<import()> sub allows callers of I<your> class to specify an C<-api_version>
+parameter. If this is supplied, then deprecation warnings are only issued for
+deprecations for api versions earlier than the one specified.
+
+You must call C<deprecated()> sub in each deprecated subroutine. When called,
+it will issue a warning using C<Carp::cluck()>. If you do not pass an explicit
+warning message, one will be generated for you.
+
+Deprecation warnings are only issued once for a given package, regardless of
+how many times the deprecated sub/method is called.
+
+=head1 BUGS
+
+Please report any bugs or feature requests to
+C<bug-package-deprecationmanager@rt.cpan.org>, or through the web interface at
+L<http://rt.cpan.org>. I will be notified, and then you'll automatically be
+notified of progress on your bug as I make changes.
+
+=head1 DONATIONS
+
+If you'd like to thank me for the work I've done on this module, please
+consider making a "donation" to me via PayPal. I spend a lot of free time
+creating free software, and would appreciate any support you'd care to offer.
+
+Please note that B<I am not suggesting that you must do this> in order
+for me to continue working on this particular software. I will
+continue to do so, inasmuch as I have in the past, for as long as it
+interests me.
+
+Similarly, a donation made in this way will probably not make me work on this
+software much more, unless I get so many donations that I can consider working
+on free software full time, which seems unlikely at best.
+
+To donate, log into PayPal and send money to autarch@urth.org or use the
+button on this page: L<http://www.urth.org/~autarch/fs-donation.html>
+
+=head1 CREDITS
+
+The idea for this functionality and some of its implementation was originally
+created as L<Class::MOP::Deprecated> by Goro Fuji.
+
=cut