add deprecation WARNING to pod

diff --git a/Changes b/Changes
index e575758..a52e61f 100644 (file)
--- a/Changes
+++ b/Changes
@@ -2,6 +2,8 @@ Revision history for Devel-Declare
 
   - added deprecated flag to metadata. No deprecation warning is given at
     runtime... for now...
+  - added "WARNING" section in pod, advising the deprecated status of this
+    module
 
 0.006018 - 2015-03-24
   - tests fixed for blead (5.21.*) (Matthew Horsfall, RT#102918)

diff --git a/lib/Devel/Declare.pm b/lib/Devel/Declare.pm
index b0f766e..20372a9 100644 (file)
--- a/lib/Devel/Declare.pm
+++ b/lib/Devel/Declare.pm
@@ -309,6 +309,36 @@ over Perl's parser, allowing the creation of new syntax.
 
 This document describes how to create a simple declarator.
 
+=head1 WARNING
+
+=for comment mst wrote this warning for MooseX::Declare, and ether adapted it for here:
+
+B<Warning:> Devel::Declare is a giant bag of crack
+originally implemented by mst with the goal of upsetting the perl core
+developers so much by its very existence that they implemented proper
+keyword handling in the core.
+
+As of perl5 version 14, this goal has been achieved, and modules such
+as L<Devel::CallParser>, L<Function::Parameters>, and L<Keyword::Simple> provide
+mechanisms to mangle perl syntax that don't require hallucinogenic
+drugs to interpret the error messages they produce.
+
+If you are using something that uses Devel::Declare, please for the love
+of kittens use something else:
+
+=over 4
+
+=item *
+
+Instead of L<TryCatch>, use L<Try::Tiny>
+
+=item *
+
+Instead of L<Method::Signatures>, use
+L<real subroutine signatures|perlsub/Signatures> (requires perl 5.22) or L<Moops>
+
+=back
+
 =head1 USAGE
 
 We'll demonstrate the usage of C<Devel::Declare> with a motivating example: a new