Extend documentation of `ActiveSupport::Notifications.subscribe` (#34721)

* Extend documentation of `ActiveSupport::Notifications.subscribe`

Add mention that a block with only one argument passed to the method
will yield an event object.

Related to #33451

* Emphasize that `SubscribeEventObjects` is a test class by adding suffix `Test`

1 files changed, 8 insertions, 1 deletions

diff --git a/activesupport/lib/active_support/notifications.rb b/activesupport/lib/active_support/notifications.rb
index 01cc363e2b..0ff32bd810 100644
--- a/activesupport/lib/active_support/notifications.rb
+++ b/activesupport/lib/active_support/notifications.rb
@@ -177,7 +177,7 @@ module ActiveSupport
       # names, or by passing a Regexp to match all events that match a pattern.
       #
       #   ActiveSupport::Notifications.subscribe(/render/) do |*args|
-      #     ...
+      #     @event = ActiveSupport::Notifications::Event.new(*args)
       #   end
       #
       # The +block+ will receive five parameters with information about the event:
@@ -189,6 +189,13 @@ module ActiveSupport
       #     id      # => String, unique ID for the instrumenter that fired the event
       #     payload # => Hash, the payload
       #   end
+      #
+      # If the block passed to the method only takes one parameter,
+      # it will yield an event object to the block:
+      #
+      #   ActiveSupport::Notifications.subscribe(/render/) do |event|
+      #     @event = event
+      #   end
       def subscribe(*args, &block)
         notifier.subscribe(*args, &block)
       end