Update docs and naming

Author: rsamoilov

lib/rage/events/events.rb

@@ -1,21 +1,41 @@
 # frozen_string_literal: true
 
+##
+# `Rage::Events` provides a simple event-driven system for publishing and subscribing to events.
+# Define events as data structures, register subscriber classes, and publish events to notify all relevant subscribers.
+# Subscribers can handle events and optionally receive additional context with each event.
+#
+# ```ruby
+# # define an event
+# UserRegistered = Data.define(:user_id)
+#
+# # define a subscriber
+# class SendWelcomeEmail
+#   include Rage::Events::Subscriber
+#   subscribe_to UserRegistered
+#
+#   def call(event)
+#     puts "Sending welcome email to user #{event.user_id}"
+#   end
+# end
+#
+# # publish the event
+# Rage::Events.publish(UserRegistered.new(user_id: 1))
+# ```
+#
 module Rage::Events
-  # Publish an event.
-  # @param event [Object] the event to publish
-  # @param metadata [Object] the metadata to publish along with the event
-  # @example
-  #   # define an event
-  #   UserRegistered = Data.define(:user_id)
-  #
-  #   # publish the event
-  #   Rage::Events.publish(UserRegistered.new(user_id: 1))
+  # Publish an event to all subscribers registered for the event's class or its ancestors.
+  # Optionally, additional context data can be provided and passed to each subscriber.
   #
-  #   # publish with metadata
-  #   Rage::Events.publish(UserRegistered.new(user_id: 1), metadata: { published_at: Time.now })
-  def self.publish(event, metadata: nil)
+  # @param event [Object] the event to publish
+  # @param context [Object] additional data to publish along with the event
+  # @example Publish an event
+  #   Rage::Events.publish(MyEvent.new)
+  # @example Publish an event with context
+  #   Rage::Events.publish(MyEvent.new, context: { published_at: Time.now })
+  def self.publish(event, context: nil)
     handler = __event_handlers[event.class] || __build_event_handler(event.class)
-    handler.call(event, metadata)
+    handler.call(event, context)
 
     nil
   end
@@ -51,30 +71,30 @@ def self.__build_event_handler(event_class)
 
       arguments = "event"
 
-      metadata_type, _ = subscriber_class.instance_method(:handle).parameters.find do |param_type, param_name|
-        param_name == :metadata || param_type == :keyrest
+      context_type, _ = subscriber_class.instance_method(:call).parameters.find do |param_type, param_name|
+        param_name == :context || param_type == :keyrest
       end
 
-      if metadata_type
-        if metadata_type == :keyreq
-          arguments += ", metadata: metadata || {}"
+      if context_type
+        if context_type == :keyreq
+          arguments += ", context: context || {}"
         else
-          arguments += ", metadata:"
+          arguments += ", context:"
         end
       end
 
       if subscriber_class.__is_deferred
         "#{subscriber_class}.enqueue(#{arguments})"
       else
-        "#{subscriber_class}.new.__handle(#{arguments})"
+        "#{subscriber_class}.new.__call(#{arguments})"
       end
     end
 
     if subscriber_calls.empty?
       ->(_, _) {}
     else
       __event_handlers[event_class] = eval <<-RUBY
-        ->(event, metadata) { #{subscriber_calls.join("; ")} }
+        ->(event, context) { #{subscriber_calls.join("; ")} }
       RUBY
     end
   end

lib/rage/events/subscriber.rb

@@ -14,16 +14,16 @@
 #   include Rage::Events::Subscriber
 #   subscribe_to MyEvent
 #
-#   def handle(event)
-#     puts "Handled event: #{event.inspect}"
+#   def call(event)
+#     puts "Received event: #{event.inspect}"
 #   end
 # end
 #
 # # Publish an event
 # Rage::Events.publish(MyEvent.new)
 # ```
 #
-# When an event matching the specified class is published, the `handle` method will be invoked with the event instance.
+# When an event matching the specified class is published, the `call` method will be invoked with the event instance.
 #
 # You can also subscribe to multiple event classes:
 #
@@ -32,7 +32,7 @@
 #   include Rage::Events::Subscriber
 #   subscribe_to EventA, EventB
 #
-#   def handle(event)
+#   def call(event)
 #     puts "Received event: #{event.inspect}"
 #   end
 # end
@@ -45,25 +45,42 @@
 #   include Rage::Events::Subscriber
 #   subscribe_to MyEvent, deferred: true
 #
-#   def handle(event)
+#   def call(event)
 #     puts "Received event in background: #{event.inspect}"
 #   end
 # end
 # ```
 #
 # Such subscriber will be executed in the background using Rage's deferred task system.
 #
+# You can also define custom error handling for exceptions raised during event processing using `rescue_from`:
+#
+# ```ruby
+# class MySubscriber
+#   include Rage::Events::Subscriber
+#   subscribe_to MyEvent
+#
+#   rescue_from StandardError do |exception|
+#     puts "An error occurred: #{exception.message}"
+#   end
+# end
+# ```
+#
+# @see ClassMethods
+#
 module Rage::Events::Subscriber
   def self.included(handler_class)
     handler_class.extend ClassMethods
   end
 
-  def handle(_)
+  # @private
+  def call(_)
   end
 
-  def __handle(event, metadata: nil)
+  # @private
+  def __call(event, context: nil)
     Rage.logger.with_context(self.class.__log_context) do
-      metadata.nil? ? handle(event) : handle(event, metadata: metadata.freeze)
+      context.nil? ? call(event) : call(event, context: context.freeze)
     rescue Exception => _e
       e = self.class.__rescue_handlers ? __run_rescue_handlers(_e) : _e
 
@@ -75,8 +92,13 @@ def __handle(event, metadata: nil)
   end
 
   module ClassMethods
+    # @private
     attr_accessor :__event_classes, :__is_deferred, :__log_context, :__rescue_handlers
 
+    # Subscribe the class to one or more events.
+    #
+    # @param event_classes [Class, Array<Class>] one or more event classes to subscribe to
+    # @param deferred [Boolean] whether to process events asynchronously
     def subscribe_to(*event_classes, deferred: false)
       @__event_classes = (@__event_classes || []) | event_classes
       @__is_deferred = !!deferred
@@ -88,10 +110,16 @@ def subscribe_to(*event_classes, deferred: false)
 
       if @__is_deferred
         include Rage::Deferred::Task
-        alias_method :perform, :__handle
+        alias_method :perform, :__call
       end
     end
 
+    # Define exception handlers for the subscriber.
+    #
+    # @param klasses [Class, Array<Class>] one or more exception classes to handle
+    # @param with [Symbol, String] the method name to call when an exception is raised
+    # @yield [exception] optional block to handle the exception
+    # @note If you do not re-raise exceptions in deferred subscribers, the subscriber will be marked as successful and Rage will not attempt to retry it.
     def rescue_from(*klasses, with: nil, &block)
       unless with
         if block_given?
@@ -116,6 +144,7 @@ def inherited(klass)
       klass.subscribe_to(*@__event_classes, deferred: @__is_deferred) if @__event_classes
     end
 
+    # @private
     def __register_rescue_handlers
       return if method_defined?(:__run_rescue_handlers, false) || @__rescue_handlers.nil?