mirror of https://github.com/rails/rails
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.
This commit is contained in:
Hartley McGuire
parent
9064735ec5
commit
f93eb16564
|
|
@ -57,15 +57,15 @@ module ActiveSupport
|
|||
# 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 @@ module ActiveSupport
|
|||
#
|
||||
# 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 @@ module ActiveSupport
|
|||
# # 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) }
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue