Allow -compatible for CMOP back-compat & add docs

diff --git a/lib/Package/DeprecationManager.pm b/lib/Package/DeprecationManager.pm
index b18cb65..4d10edc 100644 (file)
--- a/lib/Package/DeprecationManager.pm
+++ b/lib/Package/DeprecationManager.pm
@@ -48,6 +48,8 @@ sub _build_import {
         my $class = shift;
         my %args  = @_;
 
+        $args{-api_version} ||= delete $args{-compatible};
+
         $registry->{ caller() } = $args{-api_version}
             if $args{-api_version};
 
@@ -99,8 +101,55 @@ __END__
 
 =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.
+
 =cut