TEST_CODEOWNERS/rails
3
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Copy-edit deprecation relared documentation [ci skip]

Browse Source
This commit is contained in:
Rafael Mendonça França 2012-09-13 14:02:18 -03:00
parent 1726a94900
commit 8692db59af
5 changed files with 52 additions and 75 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
activesupport/CHANGELOG.md
View File

@ -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
def old_method
end
def new_method
end
deprecate :old_method => :new_method, :deprecator => deprecator
end
def self.deprecator
ActiveSupport::Deprecation.new('2.0', 'MyGem')
end
end
MyGem.new.old_method
DEPRECATION WARNING: old_method is deprecated and will be removed from MyGem 2.0
(use new_method instead). (called from <main> 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 <main> at file.rb:18)
*Piotr Niełacny & Robert Pankowecki*

38
activesupport/lib/active_support/core_ext/module/deprecation.rb
View File

@ -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.
# \Custom deprecators must respond to <tt>deprecation_warning(deprecated_method_name, message, caller_backtrace)</tt>
# method where you can implement your custom warning behavior.
#
# 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)
# 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

10
activesupport/lib/active_support/deprecation.rb
View File

@ -7,12 +7,8 @@
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 @@ class Deprecation
# 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

45
activesupport/lib/active_support/deprecation/proxy_wrappers.rb
View File

@ -27,14 +27,13 @@ def method_missing(called, *args, &block)
# 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 <tt>ActiveSupport::Deprecation</tt>
class DeprecatedObjectProxy < DeprecationProxy
def initialize(object, message, deprecator = ActiveSupport::Deprecation.instance)
@object = object
@ -52,28 +51,30 @@ def warn(callstack, called, args)
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 <tt>@_request</tt>
# variable via +request+ method and execute the same method on non-proxy
# instance variable.
#
# Default deprecator is ActiveSupport::Deprecation
# Default deprecator is <tt>ActiveSupport::Deprecation</tt>.
class DeprecatedInstanceVariableProxy < DeprecationProxy
def initialize(instance, method, var = "@#{method}", deprecator = ActiveSupport::Deprecation.instance)
@instance = instance
@ -94,13 +95,13 @@ def warn(callstack, called, args)
# 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 <tt>ActiveSupport::Deprecation</tt>.
class DeprecatedConstantProxy < DeprecationProxy
def initialize(old_const, new_const, deprecator = ActiveSupport::Deprecation.instance)
@old_const = old_const

1
activesupport/lib/active_support/deprecation/reporting.rb
View File

@ -42,6 +42,7 @@ def deprecation_warning(deprecated_method_name, message = nil, caller_backtrace
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)