Improve Deprecation API docs and guide

- Link to Deprecation::Behavior in configuring guide

  The current list of options for `config.active_support.deprecation`
  was missing the newly added `:report` option. Instead of adding the
  missing option and continuing to keep 4 different lists of the same
  options in sync, I opted to replace the list with a link to the
  options in the Behavior API docs. This had the additional advantage of
  giving more information about all of the options which was not
  mentioned in the Configuring guide.

- Use symbols for Behavior options

  It felt to me like naming the options did not make it explicit that
  those were the symbols to pass to `#behavior=`, but by adding the `:`
  that becomes more clear.

- Add some API links

  There were a few references to `behavior=`, but we may as well link to
  the actual method.

Author: skipkayhil

activesupport/lib/active_support/deprecation/behaviors.rb

@@ -57,15 +57,15 @@ class Deprecation
     # You can create a custom behavior or set any from the +DEFAULT_BEHAVIORS+
     # constant. Available behaviors are:
     #
-    # [+raise+]   Raise ActiveSupport::DeprecationException.
-    # [+stderr+]  Log all deprecation warnings to <tt>$stderr</tt>.
-    # [+log+]     Log all deprecation warnings to +Rails.logger+.
-    # [+notify+]  Use ActiveSupport::Notifications to notify +deprecation.rails+.
-    # [+report+]  Use ActiveSupport::ErrorReporter to report deprecations.
-    # [+silence+] Do nothing. On \Rails, set <tt>config.active_support.report_deprecations = false</tt> to disable all behaviors.
+    # [+:raise+]   Raise ActiveSupport::DeprecationException.
+    # [+:stderr+]  Log all deprecation warnings to <tt>$stderr</tt>.
+    # [+:log+]     Log all deprecation warnings to +Rails.logger+.
+    # [+:notify+]  Use ActiveSupport::Notifications to notify +deprecation.rails+.
+    # [+:report+]  Use ActiveSupport::ErrorReporter to report deprecations.
+    # [+:silence+] Do nothing. On \Rails, set <tt>config.active_support.report_deprecations = false</tt> to disable all behaviors.
     #
     # Setting behaviors only affects deprecations that happen after boot time.
-    # For more information you can read the documentation of the +behavior=+ method.
+    # For more information you can read the documentation of the #behavior= method.
     module Behavior
       # Whether to print a backtrace along with the warning.
       attr_accessor :debug
@@ -85,12 +85,12 @@ def disallowed_behavior
       #
       # Available behaviors:
       #
-      # [+raise+]   Raise ActiveSupport::DeprecationException.
-      # [+stderr+]  Log all deprecation warnings to <tt>$stderr</tt>.
-      # [+log+]     Log all deprecation warnings to +Rails.logger+.
-      # [+notify+]  Use ActiveSupport::Notifications to notify +deprecation.rails+.
-      # [+report+]  Use ActiveSupport::ErrorReporter to report deprecations.
-      # [+silence+] Do nothing.
+      # [+:raise+]   Raise ActiveSupport::DeprecationException.
+      # [+:stderr+]  Log all deprecation warnings to <tt>$stderr</tt>.
+      # [+:log+]     Log all deprecation warnings to +Rails.logger+.
+      # [+:notify+]  Use ActiveSupport::Notifications to notify +deprecation.rails+.
+      # [+:report+]  Use ActiveSupport::ErrorReporter to report deprecations.
+      # [+:silence+] Do nothing.
       #
       # Setting behaviors only affects deprecations that happen after boot time.
       # Deprecation warnings raised by gems are not affected by this setting
@@ -104,15 +104,17 @@ def disallowed_behavior
       #     # custom stuff
       #   }
       #
-      # If you are using \Rails, you can set <tt>config.active_support.report_deprecations = false</tt> to disable
-      # all deprecation behaviors. This is similar to the +silence+ option but more performant.
+      # If you are using \Rails, you can set
+      # <tt>config.active_support.report_deprecations = false</tt> to disable
+      # all deprecation behaviors. This is similar to the +:silence+ option but
+      # more performant.
       def behavior=(behavior)
         @behavior = Array(behavior).map { |b| DEFAULT_BEHAVIORS[b] || arity_coerce(b) }
       end
 
       # Sets the behavior for disallowed deprecations (those configured by
       # ActiveSupport::Deprecation#disallowed_warnings=) to the specified
-      # value. As with +behavior=+, this can be a single value, array, or an
+      # value. As with #behavior=, this can be a single value, array, or an
       # object that responds to +call+.
       def disallowed_behavior=(behavior)
         @disallowed_behavior = Array(behavior).map { |b| DEFAULT_BEHAVIORS[b] || arity_coerce(b) }

guides/source/configuring.md

@@ -2537,15 +2537,25 @@ The default value depends on the `config.load_defaults` target version:
 
 #### `config.active_support.deprecation`
 
-Configures the behavior of deprecation warnings. The options are `:raise`, `:stderr`, `:log`, `:notify`, and `:silence`.
+Configures the behavior of deprecation warnings. See
+[`Deprecation::Behavior`][deprecation_behavior] for a description of the
+available options.
 
-In the default generated `config/environments` files, this is set to `:log` for development and `:stderr` for test, and it is omitted for production in favor of [`config.active_support.report_deprecations`](#config-active-support-report-deprecations).
+In the default generated `config/environments` files, this is set to `:log` for
+development and `:stderr` for test, and it is omitted for production in favor of
+[`config.active_support.report_deprecations`](#config-active-support-report-deprecations).
+
+[deprecation_behavior]: https://api.rubyonrails.org/classes/ActiveSupport/Deprecation/Behavior.html#method-i-behavior-3D
 
 #### `config.active_support.disallowed_deprecation`
 
-Configures the behavior of disallowed deprecation warnings. The options are `:raise`, `:stderr`, `:log`, `:notify`, and `:silence`.
+Configures the behavior of disallowed deprecation warnings. See
+[`Deprecation::Behavior`][deprecation_behavior] for a description of the
+available options.
 
-In the default generated `config/environments` files, this is set to `:raise` for both development and test, and it is omitted for production in favor of [`config.active_support.report_deprecations`](#config-active-support-report-deprecations).
+In the default generated `config/environments` files, this is set to `:raise`
+for both development and test, and it is omitted for production in favor of
+[`config.active_support.report_deprecations`](#config-active-support-report-deprecations).
 
 #### `config.active_support.disallowed_deprecation_warnings`