Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Copy-edit deprecation relared documentation [ci skip]

  • Loading branch information...
commit 8692db59af8f0dc468b588963622e61ff982a925 1 parent 1726a94
@rafaelfranca rafaelfranca authored
View
31 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 <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*
View
38 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 <tt>deprecation_warning(deprecated_method_name, message, caller_backtrace)</tt>
+ # 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
View
10 activesupport/lib/active_support/deprecation.rb
@@ -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
View
45 activesupport/lib/active_support/deprecation/proxy_wrappers.rb
@@ -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
View
1  activesupport/lib/active_support/deprecation/reporting.rb
@@ -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)
Please sign in to comment.
Something went wrong with that request. Please try again.