Merge pull request rails#50360 from skipkayhil/hm-docs-deprecations

Improve Deprecation API docs and guide [ci-skip]

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

@@ -2544,15 +2544,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`