From 71993c6f9770b1350aa41fe8c68f1dd2c7800403 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Piotr=20Nie=C5=82acny?= <piotr.nielacny@gmail.com>
Date: Thu, 13 Sep 2012 08:38:34 +0200
Subject: Change ActiveSupport::Deprecation to class.

ActiveSupport::Deprecation is now a class rather than a module. You can
get instance of ActiveSupport::Deprecation calling #instance method.

  ActiveSupport::Deprecation.instance

But when you need to get new object od ActiveSupport::Deprecation you
need to just call #new.

  @instance = ActiveSupport::Deprecation.new

Since you can create a new object, you can change the version and the
name of the library where the deprecator concerned.

  ActiveSupport::Deprecation.new('2.0', 'MyGem')

If you need use another deprecator instance you can select it in the
options of deprecate method.

  deprecate :method, :deprecator => deprecator_instance

Documentation has been updated.
---
 .../active_support/core_ext/module/deprecation.rb  | 34 +++++++++++++++++++++-
 1 file changed, 33 insertions(+), 1 deletion(-)

(limited to 'activesupport/lib/active_support/core_ext')

diff --git a/activesupport/lib/active_support/core_ext/module/deprecation.rb b/activesupport/lib/active_support/core_ext/module/deprecation.rb
index 9e77ac3c45..9affd38baa 100644
--- a/activesupport/lib/active_support/core_ext/module/deprecation.rb
+++ b/activesupport/lib/active_support/core_ext/module/deprecation.rb
@@ -1,10 +1,42 @@
 require 'active_support/deprecation/method_wrappers'
 
 class Module
-  # Declare that a method has been deprecated.
   #   deprecate :foo
   #   deprecate :bar => 'message'
   #   deprecate :foo, :bar, :baz => 'warning!', :qux => 'gone!'
+  #
+  # You can use custom deprecator instance
+  #   deprecate :foo, :deprecator => MyLib::Deprecator.new
+  #   deprecate :foo, :bar => "warning!", :deprecator => MyLib::Deprecator.new
+  #
+  # \Custom deprecators must respond to one method
+  # [deprecation_warning(deprecated_method_name, message, caller_backtrace)] will be called with the deprecated
+  #                                                                          method name, the message it was declared
+  #                                                                          with and caller_backtrace. Implement
+  #                                                                          whatever warning behavior you like here.
+  #
+  # Example
+  #    class MyLib::Deprecator
+  #
+  #      def deprecation_warning(deprecated_method_name, message, caller_backtrace)
+  #         message = "#{method_name} is deprecated and will be removed from MyLibrary | #{message}"
+  #         Kernel.warn message
+  #      end
+  #
+  #    end
+  #
+  #    module MyLib
+  #      mattr_accessor :deprecator
+  #      self.deprecator = Deprecator.new
+  #    end
+  #
+  # When we deprecate method
+  #    class MyLib::Bar
+  #      deprecate :foo => "this is very old method", :deprecator => MyLib.deprecator
+  #    end
+  #
+  # It will build deprecation message and invoke deprecator warning by calling
+  #   MyLib.deprecator.deprecation_warning(:foo, "this is a very old method", caller)
   def deprecate(*method_names)
     ActiveSupport::Deprecation.deprecate_methods(self, *method_names)
   end
-- 
cgit v1.2.3