Improve ActiveSupport::ErrorReporter API doc [ci-skip]

This moves some of the documentation from the `ErrorReporter` class
directly to the `handle` and `record` methods, and fleshes those out.
This also tweaks the documentation of the other `ErrorReporter` methods.

Author: jonathanhefner

activesupport/lib/active_support/error_reporter.rb

@@ -3,46 +3,24 @@
 module ActiveSupport
   # +ActiveSupport::ErrorReporter+ is a common interface for error reporting services.
   #
-  # To rescue and report any unhandled error, you can use the +handle+ method:
+  # To rescue and report any unhandled error, you can use the #handle method:
   #
   #   Rails.error.handle do
   #     do_something!
   #   end
   #
   # If an error is raised, it will be reported and swallowed.
   #
-  # Alternatively if you want to report the error but not swallow it, you can use +record+
+  # Alternatively, if you want to report the error but not swallow it, you can use #record:
   #
   #   Rails.error.record do
   #     do_something!
   #   end
   #
-  # Both methods can be restricted to only handle a specific exception class
+  # Both methods can be restricted to handle only a specific error class:
   #
   #   maybe_tags = Rails.error.handle(Redis::BaseError) { redis.get("tags") }
   #
-  # You can also pass some extra context information that may be used by the error subscribers:
-  #
-  #   Rails.error.handle(context: { section: "admin" }) do
-  #     # ...
-  #   end
-  #
-  # Additionally a +severity+ can be passed along to communicate how important the error report is.
-  # +severity+ can be one of +:error+, +:warning+, or +:info+. Handled errors default to the +:warning+
-  # severity, and unhandled ones to +:error+.
-  #
-  # A +source+ can also be specified, describing where the error originates from. Error subscribers can
-  # use this to ignore certain errors. For instance, ActiveSupport may report internal errors
-  # such as cache failures with a source like "redis_cache_store.active_support".
-  # The default +source+ is "application".
-  #
-  # Both +handle+ and +record+ pass through the return value from the block. In the case of +handle+
-  # rescuing an error, a fallback can be provided. The fallback must be a callable whose result will
-  # be returned when the block raises and is handled:
-  #
-  #   user = Rails.error.handle(fallback: -> { User.anonymous }) do
-  #     User.find_by(params)
-  #   end
   class ErrorReporter
     SEVERITIES = %i(error warning info)
     DEFAULT_SOURCE = "application"
@@ -54,26 +32,78 @@ def initialize(*subscribers, logger: nil)
       @logger = logger
     end
 
-    # Report any unhandled exception, and swallow it.
+    # Evaluates the given block, reporting and swallowing any unhandled error.
+    # If no error is raised, returns the return value of the block. Otherwise,
+    # returns the result of +fallback.call+, or +nil+ if +fallback+ is not
+    # specified.
     #
+    #   # Will report a TypeError to all subscribers and return nil.
     #   Rails.error.handle do
     #     1 + '1'
     #   end
     #
+    # Can be restricted to handle only a specific error class:
+    #
+    #   maybe_tags = Rails.error.handle(Redis::BaseError) { redis.get("tags") }
+    #
+    # ==== Options
+    #
+    # * +:severity+ - This value is passed along to subscribers to indicate how
+    #   important the error report is. Can be +:error+, +:warning+, or +:info+.
+    #   Defaults to +:warning+.
+    #
+    # * +:context+ - Extra information that is passed along to subscribers. For
+    #   example:
+    #
+    #     Rails.error.handle(context: { section: "admin" }) do
+    #       # ...
+    #     end
+    #
+    # * +:fallback+ - A callable that provides +handle+'s return value when an
+    #   unhandled error is raised. For example:
+    #
+    #     user = Rails.error.handle(fallback: -> { User.anonymous }) do
+    #       User.find_by(params)
+    #     end
+    #
+    # * +:source+ - This value is passed along to subscribers to indicate the
+    #   source of the error. Subscribers can use this value to ignore certain
+    #   errors. Defaults to <tt>"application"</tt>.
     def handle(error_class = StandardError, severity: :warning, context: {}, fallback: nil, source: DEFAULT_SOURCE)
       yield
     rescue error_class => error
       report(error, handled: true, severity: severity, context: context, source: source)
       fallback.call if fallback
     end
 
-    # Report any unhandled exception, but do not swallow it.
+    # Evaluates the given block, reporting and re-raising any unhandled error.
+    # If no error is raised, returns the return value of the block.
     #
+    #   # Will report a TypeError to all subscribers and re-raise it.
     #   Rails.error.record do
-    #     # Will report the TypeError to all subscribers and then raise it.
     #     1 + '1'
     #   end
     #
+    # Can be restricted to handle only a specific error class:
+    #
+    #   tags = Rails.error.record(Redis::BaseError) { redis.get("tags") }
+    #
+    # ==== Options
+    #
+    # * +:severity+ - This value is passed along to subscribers to indicate how
+    #   important the error report is. Can be +:error+, +:warning+, or +:info+.
+    #   Defaults to +:error+.
+    #
+    # * +:context+ - Extra information that is passed along to subscribers. For
+    #   example:
+    #
+    #     Rails.error.record(context: { section: "admin" }) do
+    #       # ...
+    #     end
+    #
+    # * +:source+ - This value is passed along to subscribers to indicate the
+    #   source of the error. Subscribers can use this value to ignore certain
+    #   errors. Defaults to <tt>"application"</tt>.
     def record(error_class = StandardError, severity: :error, context: {}, source: DEFAULT_SOURCE)
       yield
     rescue error_class => error
@@ -85,7 +115,7 @@ def record(error_class = StandardError, severity: :error, context: {}, source: D
     #
     #   report(Exception, handled: Boolean, severity: (:error OR :warning OR :info), context: Hash, source: String)
     #
-    # The +report+ method +should+ never raise an error.
+    # The +report+ method <b>should never</b> raise an error.
     def subscribe(subscriber)
       unless subscriber.respond_to?(:report)
         raise ArgumentError, "Error subscribers must respond to #report"
@@ -108,19 +138,21 @@ def disable(subscriber)
       end
     end
 
-    # Update the execution context that is accessible to error subscribers
+    # Update the execution context that is accessible to error subscribers. Any
+    # context passed to #handle, #record, or #report will be merged with the
+    # context set here.
     #
     #   Rails.error.set_context(section: "checkout", user_id: @user.id)
     #
-    # Any context passed to +handle+, +record+, or +report+ will be merged with the context set here.
-    # See +ActiveSupport::ExecutionContext.set+
     def set_context(...)
       ActiveSupport::ExecutionContext.set(...)
     end
 
-    # When the block based +handle+ and +record+ methods are not suitable, you can directly use +report+
+    # Report an error directly to subscribers. You can use this method when the
+    # block-based #handle and #record methods are not suitable.
     #
     #   Rails.error.report(error)
+    #
     def report(error, handled: true, severity: handled ? :warning : :error, context: {}, source: DEFAULT_SOURCE)
       unless SEVERITIES.include?(severity)
         raise ArgumentError, "severity must be one of #{SEVERITIES.map(&:inspect).join(", ")}, got: #{severity.inspect}"