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`

3 files changed, 22 insertions, 3 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
diff --git a/activesupport/test/notifications_test.rb b/activesupport/test/notifications_test.rb
index 54fd4345fb..4e0aef2cc7 100644
--- a/activesupport/test/notifications_test.rb
+++ b/activesupport/test/notifications_test.rb
@@ -26,7 +26,7 @@ module Notifications
     end
   end
 
-  class SubscribeEventObjects < TestCase
+  class SubscribeEventObjectsTest < TestCase
     def test_subscribe_events
       events = []
       @notifier.subscribe do |event|
diff --git a/guides/source/active_support_instrumentation.md b/guides/source/active_support_instrumentation.md
index 64db141381..5e68b3f400 100644
--- a/guides/source/active_support_instrumentation.md
+++ b/guides/source/active_support_instrumentation.md
@@ -648,6 +648,18 @@ ActiveSupport::Notifications.subscribe "process_action.action_controller" do |*a
 end
 ```
 
+You may also pass block with only one argument, it will yield an event object to the block:
+
+```ruby
+ActiveSupport::Notifications.subscribe "process_action.action_controller" do |event|
+  event.name      # => "process_action.action_controller"
+  event.duration  # => 10 (in milliseconds)
+  event.payload   # => {:extra=>information}
+
+  Rails.logger.info "#{event} Received!"
+end
+```
+
 Most times you only care about the data itself. Here is a shortcut to just get the data.
 
 ```ruby
@@ -672,7 +684,7 @@ Creating custom events
 Adding your own events is easy as well. `ActiveSupport::Notifications` will take care of
 all the heavy lifting for you. Simply call `instrument` with a `name`, `payload` and a block.
 The notification will be sent after the block returns. `ActiveSupport` will generate the start and end times
-and add the instrumenter's unique ID. All data passed into the `instrument` call will make 
+and add the instrumenter's unique ID. All data passed into the `instrument` call will make
 it into the payload.
 
 Here's an example: