add standard documentation to deprecate
authorRobin Barker <Robin.Barker@npl.co.uk>
Thu, 26 Feb 2009 17:08:35 +0000 (17:08 +0000)
committerRafael Garcia-Suarez <rgarciasuarez@gmail.com>
Fri, 27 Feb 2009 14:23:45 +0000 (15:23 +0100)
lib/deprecate.pm

index e33d8c5..d016d77 100644 (file)
@@ -51,3 +51,54 @@ EOM
 }
 
 1;
+
+__END__
+
+=head1 NAME
+
+deprecate - Perl (core) extension for deprecating the core version of a module,
+           in favour of the version on CPAN.
+
+
+=head1 SYNOPSIS
+
+    use deprecate;     # always deprecate the module in which this occurs
+
+    use if $[ > 5.010, 'deprecate';    # conditionally deprecate the module
+
+
+=head1 DESCRIPTION
+
+This module is used using C<use deprecate;> (or something that calls
+C<< deprecate->import() >>, for example C<use if COND, deprecate;>).
+
+If the module that includes C<use deprecate> is located in a core library
+directory, a deprecation warning is issued, encouraging the user to use
+the version on CPAN.  If that module is located in a site library, it is
+the CPAN version, and no warning is issued.
+
+=head2 EXPORT
+
+None by default.  The only method is C<import>, called by C<use deprecate;>.
+
+
+=head1 SEE ALSO
+
+First example to C<use deprecate;> was L<Switch>.
+
+
+=head1 AUTHOR
+
+Original version by Nicholas Clark
+
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright (C) 2009 
+
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself, either Perl version 5.10.0 or,
+at your option, any later version of Perl 5 you may have available.
+
+
+=cut