2 files changed, 30 insertions, 3 deletions
diff --git a/activesupport/lib/active_support/deprecation.rb b/activesupport/lib/active_support/deprecation.rb
index 297a17850e..621cc14cea 100644
--- a/activesupport/lib/active_support/deprecation.rb
+++ b/activesupport/lib/active_support/deprecation.rb
@@ -71,11 +71,13 @@ module ActiveSupport
     module ClassMethods
       # Declare that a method has been deprecated.
       def deprecate(*method_names)
+        options = method_names.last.is_a?(Hash) ? method_names.pop : {}
+        method_names = method_names + options.keys
         method_names.each do |method_name|
           alias_method_chain(method_name, :deprecation) do |target, punctuation|
             class_eval(<<-EOS, __FILE__, __LINE__)
               def #{target}_with_deprecation#{punctuation}(*args, &block)
-                ::ActiveSupport::Deprecation.warn(self.class.deprecated_method_warning(:#{method_name}), caller)
+                ::ActiveSupport::Deprecation.warn(self.class.deprecated_method_warning(:#{method_name}, #{options[method_name].inspect}), caller)
                 #{target}_without_deprecation#{punctuation}(*args, &block)
               end
             EOS
@@ -83,8 +85,13 @@ module ActiveSupport
         end
       end
 
-      def deprecated_method_warning(method_name)
-        "#{method_name} is deprecated and will be removed from Rails #{deprecation_horizon}"
+      def deprecated_method_warning(method_name, message=nil)
+        warning = "#{method_name} is deprecated and will be removed from Rails #{deprecation_horizon}"
+        case message
+          when Symbol then "#{warning} (use #{message} instead)"
+          when String then "#{warning} (#{message})"
+          else warning
+        end
       end
 
       def deprecation_horizon
diff --git a/activesupport/test/deprecation_test.rb b/activesupport/test/deprecation_test.rb
index bbcee24f5c..21baa11a80 100644
--- a/activesupport/test/deprecation_test.rb
+++ b/activesupport/test/deprecation_test.rb
@@ -17,6 +17,13 @@ class Deprecatee
   def one(a) a end
   def multi(a,b,c) [a,b,c] end
   deprecate :none, :one, :multi
+
+  def a; end
+  def b; end
+  def c; end
+  def d; end
+  def e; end
+  deprecate :a, :b, :c => :e, :d => "you now need to do something extra for this one"
 end
 
 
@@ -108,4 +115,17 @@ class DeprecationTest < Test::Unit::TestCase
     assert_not_deprecated { @dtc.partially }
     ActiveSupport::Deprecation.silenced = false
   end
+
+  def test_deprecation_without_explanation
+    assert_deprecated { @dtc.a }
+    assert_deprecated { @dtc.b }
+  end
+
+  def test_deprecation_with_alternate_method
+    assert_deprecated(/use e instead/) { @dtc.c }
+  end
+
+  def test_deprecation_with_explicit_message
+    assert_deprecated(/you now need to do something extra for this one/) { @dtc.d }
+  end
 end