Better docs on schematized objects + cleanup

Author: adrianna-chang-shopify

activesupport/lib/active_support/event_reporter.rb

@@ -87,9 +87,26 @@ def clear
   #   #  }
   #
   # The +notify+ API can receive either an event name and a payload hash, or an event object.
-  # If an event object is used, it will be passed through to subscribers as-is, and the name of the
+
+  # ==== Event Objects
+  #
+  # If an event object is passed to the +notify+ API, it will be passed through to subscribers as-is, and the name of the
   # object's class will be used as the event name.
   #
+  # class UserCreatedEvent
+  #   def initialize(id:, name:)
+  #     @id = id
+  #     @name = name
+  #   end
+  #
+  #   def to_h
+  #     {
+  #       id: @id,
+  #       name: @name
+  #     }
+  #   end
+  # end
+  #
   #   Rails.event.notify(UserCreatedEvent.new(id: 123, name: "John Doe"))
   #   # Emits event:
   #   #  {
@@ -99,7 +116,8 @@ def clear
   #   #    source_location: { filepath: "path/to/file.rb", lineno: 123, label: "UserService#create" }
   #   #  }
   #
-  # These objects should represent schematized events and be serializable.
+  # An event is any Ruby object representing a schematized event. While payload hashes allow arbitrary,
+  # implicitly-structured data, event objects are intended to enforce a particular schema.
   #
   # ==== Default Encoders
   #
@@ -249,7 +267,6 @@ def initialize(*subscribers, raise_on_error: false, tags: nil)
     #   source_location: Hash (The source location of the event, containing the filepath, lineno, and label)
     #
     def subscribe(subscriber)
-      return if @subscribers.include?(subscriber)
       unless subscriber.respond_to?(:emit)
         raise ArgumentError, "Event subscriber #{subscriber.class.name} must respond to #emit"
       end

activesupport/lib/active_support/testing/event_reporter_assertions.rb

@@ -3,8 +3,9 @@
 
 module ActiveSupport
   module Testing
+    # Provides test helpers for asserting on ActiveSupport::EventReporter events.
     module EventReporterAssertions
-      module EventCollector # :nodoc:
+      module EventCollector # :nodoc: all
         @subscribed = false
         @mutex = Mutex.new
 
@@ -21,6 +22,7 @@ def inspect
 
           def matches?(name, payload, tags)
             return false unless name == event_data[:name]
+
             if payload && payload.is_a?(Hash)
               return false unless payload.all? do |k, v|
                 if v.is_a?(Regexp)
@@ -30,6 +32,7 @@ def matches?(name, payload, tags)
                 end
               end
             end
+
             return false unless tags.all? do |k, v|
               if v.is_a?(Regexp)
                 event_data.dig(:tags, k).to_s.match?(v)
@@ -40,6 +43,7 @@ def matches?(name, payload, tags)
             true
           end
         end
+
         class << self
           def emit(event)
             event_recorders&.each do |events|