Improve documentation on ActiveSupport::Deprecation.

4 files changed, 16 insertions, 3 deletions

diff --git a/activesupport/lib/active_support/deprecation.rb b/activesupport/lib/active_support/deprecation.rb
index e1b8211d68..e3e63ce316 100644
--- a/activesupport/lib/active_support/deprecation.rb
+++ b/activesupport/lib/active_support/deprecation.rb
@@ -4,7 +4,7 @@ require 'active_support/deprecation/method_wrappers'
 require 'active_support/deprecation/proxy_wrappers'
 
 module ActiveSupport
-  module Deprecation #:nodoc:
+  module Deprecation
     class << self
       # The version the deprecated behavior will be removed, by default.
       attr_accessor :deprecation_horizon
diff --git a/activesupport/lib/active_support/deprecation/behaviors.rb b/activesupport/lib/active_support/deprecation/behaviors.rb
index f54f65dcf0..da4af339fc 100644
--- a/activesupport/lib/active_support/deprecation/behaviors.rb
+++ b/activesupport/lib/active_support/deprecation/behaviors.rb
@@ -7,10 +7,17 @@ module ActiveSupport
       # Whether to print a backtrace along with the warning.
       attr_accessor :debug
 
+      # Returns the set behaviour or if one isn't set, defaults to +:stderr+
       def behavior
         @behavior ||= [DEFAULT_BEHAVIORS[:stderr]]
       end
 
+      # Sets the behaviour to the specified value. Can be a single value or an array.
+      #
+      # Examples
+      #
+      #   ActiveSupport::Deprecation.behavior = :stderr
+      #   ActiveSupport::Deprecation.behavior = [:stderr, :log]
       def behavior=(behavior)
         @behavior = Array.wrap(behavior).map { |b| DEFAULT_BEHAVIORS[b] || b }
       end
diff --git a/activesupport/lib/active_support/deprecation/reporting.rb b/activesupport/lib/active_support/deprecation/reporting.rb
index 6a7b11c7e0..c7723d139b 100644
--- a/activesupport/lib/active_support/deprecation/reporting.rb
+++ b/activesupport/lib/active_support/deprecation/reporting.rb
@@ -2,7 +2,13 @@ module ActiveSupport
   module Deprecation
     class << self
       attr_accessor :silenced
-
+      
+      # Outputs a deprecation warning to the output configured by <tt>ActiveSupport::Deprecation.behavior</tt>
+      #
+      # Example:
+      #
+      #   ActiveSupport::Deprecation.warn("something broke!")
+      #   #=> "DEPRECATION WARNING: something broke! (called from your_code.rb:1)"
       def warn(message = nil, callstack = caller)
         return if silenced
         deprecation_message(callstack, message).tap do |m|
diff --git a/railties/guides/source/configuring.textile b/railties/guides/source/configuring.textile
index fa86e0f039..73147efd3a 100644
--- a/railties/guides/source/configuring.textile
+++ b/railties/guides/source/configuring.textile
@@ -471,7 +471,7 @@ You might have expected an instance of Array.
 The error occurred while evaluating nil.each
 </plain>
 
-*+active_support.deprecation_behavior+* Sets up deprecation reporting for environments, defaulting to +log+ for development, +notify+ for production and +stderr+ for test. If a value isn't set for +config.active_support.deprecation+ then this initializer will prompt the user to configure this line in the current environment's +config/environments+ file.
+*+active_support.deprecation_behavior+* Sets up deprecation reporting for environments, defaulting to +:log+ for development, +:notify+ for production and +:stderr+ for test. If a value isn't set for +config.active_support.deprecation+ then this initializer will prompt the user to configure this line in the current environment's +config/environments+ file. Can be set to an array of values.
 
 *+active_support.initialize_time_zone+* Sets the default time zone for the application based off the +config.time_zone+ setting, which defaults to "UTC".