From 8692db59af8f0dc468b588963622e61ff982a925 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rafael=20Mendon=C3=A7a=20Fran=C3=A7a?= Date: Thu, 13 Sep 2012 14:02:18 -0300 Subject: Copy-edit deprecation relared documentation [ci skip] --- activesupport/CHANGELOG.md | 31 ++++++++------- .../active_support/core_ext/module/deprecation.rb | 38 +++++------------- activesupport/lib/active_support/deprecation.rb | 10 +---- .../active_support/deprecation/proxy_wrappers.rb | 45 +++++++++++----------- .../lib/active_support/deprecation/reporting.rb | 1 + 5 files changed, 51 insertions(+), 74 deletions(-) diff --git a/activesupport/CHANGELOG.md b/activesupport/CHANGELOG.md index 6dff6de83a..0b09f73383 100644 --- a/activesupport/CHANGELOG.md +++ b/activesupport/CHANGELOG.md @@ -5,30 +5,29 @@ You can choose which instance of the deprecator will be used. - deprecate :method_name, :deprecator => deprecator_instance + deprecate :method_name, :deprecator => deprecator_instance You can use ActiveSupport::Deprecation in your gem. - require 'active_support/deprecation' - require 'active_support/core_ext/module/deprecation' + require 'active_support/deprecation' + require 'active_support/core_ext/module/deprecation' - class MyGem - def old_method - end - deprecate :old_method => :new_method, :deprecator => deprecator + class MyGem + def self.deprecator + ActiveSupport::Deprecation.new('2.0', 'MyGem') + end - def new_method - end + def old_method + end - def self.deprecator - ActiveSupport::Deprecation.new('2.0', 'MyGem') - end - end + def new_method + end - MyGem.new.old_method + deprecate :old_method => :new_method, :deprecator => deprecator + end - DEPRECATION WARNING: old_method is deprecated and will be removed from MyGem 2.0 - (use new_method instead). (called from
at file.rb:18) + MyGem.new.old_method + # => DEPRECATION WARNING: old_method is deprecated and will be removed from MyGem 2.0 (use new_method instead). (called from
at file.rb:18) *Piotr Niełacny & Robert Pankowecki* diff --git a/activesupport/lib/active_support/core_ext/module/deprecation.rb b/activesupport/lib/active_support/core_ext/module/deprecation.rb index 9affd38baa..34ec6a3d8f 100644 --- a/activesupport/lib/active_support/core_ext/module/deprecation.rb +++ b/activesupport/lib/active_support/core_ext/module/deprecation.rb @@ -5,38 +5,20 @@ class Module # deprecate :bar => 'message' # deprecate :foo, :bar, :baz => 'warning!', :qux => 'gone!' # - # You can use custom deprecator instance + # You can also 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 + # \Custom deprecators must respond to deprecation_warning(deprecated_method_name, message, caller_backtrace) + # method where you can implement your custom warning behavior. # - # It will build deprecation message and invoke deprecator warning by calling - # MyLib.deprecator.deprecation_warning(:foo, "this is a very old method", caller) + # 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 def deprecate(*method_names) ActiveSupport::Deprecation.deprecate_methods(self, *method_names) end diff --git a/activesupport/lib/active_support/deprecation.rb b/activesupport/lib/active_support/deprecation.rb index 678cbbcbf2..b3f5fde335 100644 --- a/activesupport/lib/active_support/deprecation.rb +++ b/activesupport/lib/active_support/deprecation.rb @@ -7,12 +7,8 @@ require 'active_support/deprecation/proxy_wrappers' require 'singleton' module ActiveSupport - # \Deprecation specifies the API used by Rails to deprecate - # methods, instance variables, objects and constants. - # The API depends on four methods: - # - # * +initialize+ which expects two parameters - # described below; + # \Deprecation specifies the API used by Rails to deprecate methods, instance + # variables, objects and constants. class Deprecation include Singleton include InstanceDelegator @@ -26,8 +22,6 @@ module ActiveSupport # It accepts two parameters on initialization. The first is an version of library # and the second is an library name # - # == Example - # # ActiveSupport::Deprecation.new('2.0', 'MyLibrary') def initialize(deprecation_horizon = '4.1', gem_name = 'Rails') self.gem_name = gem_name diff --git a/activesupport/lib/active_support/deprecation/proxy_wrappers.rb b/activesupport/lib/active_support/deprecation/proxy_wrappers.rb index 2b8282c34e..17e69c34a5 100644 --- a/activesupport/lib/active_support/deprecation/proxy_wrappers.rb +++ b/activesupport/lib/active_support/deprecation/proxy_wrappers.rb @@ -27,14 +27,13 @@ module ActiveSupport # This DeprecatedObjectProxy transforms object to depracated object. # - # Example # @old_object = DeprecatedObjectProxy.new(Object.new, "Don't use this object anymore!") - # Example with custom deprecator # @old_object = DeprecatedObjectProxy.new(Object.new, "Don't use this object anymore!", deprecator_instance) # - # When someone execute any method expect +inspect+ on proxy object this will trigger +warn+ method on +deprecator_instance+ + # When someone execute any method expect +inspect+ on proxy object this will + # trigger +warn+ method on +deprecator_instance+. # - # Default deprecator is ActiveSupport::Deprecation + # Default deprecator is ActiveSupport::Deprecation class DeprecatedObjectProxy < DeprecationProxy def initialize(object, message, deprecator = ActiveSupport::Deprecation.instance) @object = object @@ -52,28 +51,30 @@ module ActiveSupport end end - # This DeprecatedInstanceVariableProxy transforms instance variable to depracated instance variable. + # This DeprecatedInstanceVariableProxy transforms instance variable to + # depracated instance variable. # - # Example - # class Example - # def initialize(deprecator) - # @request = ActiveSupport::Deprecation::DeprecatedInstanceVariableProxy.new(self, :request, :@request, deprecator) - # @_request = :a_request - # end + # class Example + # def initialize(deprecator) + # @request = ActiveSupport::Deprecation::DeprecatedInstanceVariableProxy.new(self, :request, :@request, deprecator) + # @_request = :a_request + # end # - # def request + # def request # @_request # end # - # def old_request + # def old_request # @request - # end - # end + # end + # end # - # When someone execute any method on @request variable this will trigger +warn+ method on +deprecator_instance+ - # and will fetch @_request variable via +request+ method and execute the same method on non-proxy instance variable. + # When someone execute any method on @request variable this will trigger + # +warn+ method on +deprecator_instance+ and will fetch @_request + # variable via +request+ method and execute the same method on non-proxy + # instance variable. # - # Default deprecator is ActiveSupport::Deprecation + # Default deprecator is ActiveSupport::Deprecation. class DeprecatedInstanceVariableProxy < DeprecationProxy def initialize(instance, method, var = "@#{method}", deprecator = ActiveSupport::Deprecation.instance) @instance = instance @@ -94,13 +95,13 @@ module ActiveSupport # This DeprecatedConstantProxy transforms constant to depracated constant. # - # Example # OLD_CONST = ActiveSupport::Deprecation::DeprecatedConstantProxy.new('OLD_CONST', 'NEW_CONST') - # Example with custom deprecator # OLD_CONST = ActiveSupport::Deprecation::DeprecatedConstantProxy.new('OLD_CONST', 'NEW_CONST', deprecator_instance) - # When someone use old constant this will trigger +warn+ method on +deprecator_instance+ # - # Default deprecator is ActiveSupport::Deprecation + # When someone use old constant this will trigger +warn+ method on + # +deprecator_instance+. + # + # Default deprecator is ActiveSupport::Deprecation. class DeprecatedConstantProxy < DeprecationProxy def initialize(old_const, new_const, deprecator = ActiveSupport::Deprecation.instance) @old_const = old_const diff --git a/activesupport/lib/active_support/deprecation/reporting.rb b/activesupport/lib/active_support/deprecation/reporting.rb index cf91ca1acb..02e8ff7c87 100644 --- a/activesupport/lib/active_support/deprecation/reporting.rb +++ b/activesupport/lib/active_support/deprecation/reporting.rb @@ -42,6 +42,7 @@ module ActiveSupport private # Outputs a deprecation warning message + # # ActiveSupport::Deprecation.deprecated_method_warning(:method_name) # # => "method_name is deprecated and will be removed from Rails #{deprecation_horizon}" # ActiveSupport::Deprecation.deprecated_method_warning(:method_name, :another_method) -- cgit v1.2.3