Copy-edit deprecation relared documentation [ci skip]

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 <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*
 
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 <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
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 <tt>ActiveSupport::Deprecation</tt>
     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 <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 @@ 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 <tt>ActiveSupport::Deprecation</tt>.
     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)