cmdx 1.0.0 → 1.1.0

data/lib/cmdx/core_ext/module.rb

@@ -2,65 +2,39 @@
 
 module CMDx
   module CoreExt
-    # Extensions to Module that provide CMDx-specific metaprogramming capabilities.
-    #
-    # ModuleExtensions adds method delegation and attribute setting functionality
-    # used throughout the CMDx framework. These methods enable declarative
-    # programming patterns and automatic method generation.
-    #
-    # @example Method delegation
-    #   class Task
-    #     __cmdx_attr_delegator :name, :email, to: :user
-    #     __cmdx_attr_delegator :save, to: :record, private: true
-    #   end
-    #
-    # @example Attribute settings
-    #   class Task
-    #     __cmdx_attr_setting :default_options, default: -> { {} }
-    #     __cmdx_attr_setting :configuration, default: {}
-    #   end
-    #
-    # @see Task Tasks that use module extensions for delegation
-    # @see Parameter Parameters that use attribute settings
+    # Extensions for Ruby's Module class that provide attribute delegation and settings functionality.
+    # These extensions are automatically included in all modules when CMDx is loaded.
     module ModuleExtensions
 
-      # Create delegator methods that forward calls to another object.
+      # Creates delegated methods that forward calls to another object or class.
+      # Supports method name prefixing, privacy levels, and optional method existence checking.
       #
-      # This method generates instance methods that delegate to methods on
-      # another object. It supports method visibility controls and optional
-      # missing method handling.
-      #
-      # @param methods [Array<Symbol>] method names to delegate
+      # @param methods [Array<Symbol>] the method names to delegate
       # @param options [Hash] delegation options
-      # @option options [Symbol] :to target object method name (required)
-      # @option options [Boolean] :allow_missing whether to allow missing methods
-      # @option options [Boolean] :private make delegated methods private
-      # @option options [Boolean] :protected make delegated methods protected
-      # @return [void]
+      # @option options [Symbol] :to the target object or :class to delegate to
+      # @option options [Boolean] :allow_missing (false) whether to allow delegation to non-existent methods
+      # @option options [Boolean] :protected (false) whether to make the delegated method protected
+      # @option options [Boolean] :private (false) whether to make the delegated method private
+      # @option options [String, Symbol] :prefix optional prefix for the delegated method name
+      # @option options [String, Symbol] :suffix optional suffix for the delegated method name
       #
-      # @example Basic delegation
-      #   class User
-      #     __cmdx_attr_delegator :first_name, :last_name, to: :profile
-      #     # Creates: def first_name; profile.first_name; end
-      #   end
+      # @return [void]
+      # @raise [NoMethodError] when delegating to a non-existent method and :allow_missing is false
       #
-      # @example Private delegation
+      # @example Delegate methods to an instance variable
       #   class Task
-      #     __cmdx_attr_delegator :validate, to: :validator, private: true
-      #   end
+      #     def initialize
+      #       @logger = Logger.new
+      #     end
       #
-      # @example Class delegation
-      #   class Task
-      #     __cmdx_attr_delegator :configuration, to: :class
+      #     cmdx_attr_delegator :info, :warn, :error, to: :@logger
       #   end
       #
-      # @example With missing method handling
-      #   class Task
-      #     __cmdx_attr_delegator :optional_method, to: :service, allow_missing: true
+      # @example Delegate with prefix and privacy
+      #   class Workflow
+      #     cmdx_attr_delegator :perform, to: :task, prefix: 'execute_', private: true
       #   end
-      #
-      # @raise [NoMethodError] if target object doesn't respond to method and allow_missing is false
-      def __cmdx_attr_delegator(*methods, **options)
+      def cmdx_attr_delegator(*methods, **options)
         methods.each do |method|
           method_name = Utils::NameAffix.call(method, options.fetch(:to), options)
 
@@ -83,53 +57,36 @@ module CMDx
         end
       end
 
-      # Create class-level attribute accessor with lazy evaluation and inheritance.
+      # Creates a singleton method for accessing inheritable settings with caching and default values.
+      # Settings are inherited from superclass and can have default values via blocks or static values.
       #
-      # This method generates a class method that provides lazy-loaded attribute
-      # access with inheritance support. Values are cached and can be initialized
-      # with default values or procs.
+      # @param method [Symbol] the name of the setting method to create
+      # @param options [Hash] setting options
+      # @option options [Object, Proc] :default the default value or a proc that returns the default value
       #
-      # @param method [Symbol] name of the attribute method
-      # @param options [Hash] attribute options
-      # @option options [Object, Proc] :default default value or proc to generate value
       # @return [void]
       #
-      # @example Simple attribute setting
-      #   class Task
-      #     __cmdx_attr_setting :timeout, default: 30
-      #   end
-      #   # Task.timeout => 30
-      #
-      # @example Dynamic default with proc
-      #   class Task
-      #     __cmdx_attr_setting :timestamp, default: -> { Time.now }
-      #   end
-      #   # Task.timestamp => current time (evaluated lazily)
-      #
-      # @example Inherited settings
+      # @example Define a setting with a default value
       #   class BaseTask
-      #     __cmdx_attr_setting :options, default: {retry: 3}
+      #     cmdx_attr_setting :timeout, default: 30
       #   end
       #
-      #   class ProcessTask < BaseTask
-      #   end
-      #   # ProcessTask.options => {retry: 3} (inherited from BaseTask)
+      #   BaseTask.timeout # => 30
       #
-      # @example Hash settings (automatically duplicated)
+      # @example Define a setting with a dynamic default
       #   class Task
-      #     __cmdx_attr_setting :config, default: {}
+      #     cmdx_attr_setting :retry_count, default: -> { ENV['RETRY_COUNT']&.to_i || 3 }
       #   end
-      #   # Each class gets its own copy of the hash
-      def __cmdx_attr_setting(method, **options)
+      def cmdx_attr_setting(method, **options)
         define_singleton_method(method) do
           @cmd_facets ||= {}
           return @cmd_facets[method] if @cmd_facets.key?(method)
 
-          value = superclass.__cmdx_try(method)
+          value = superclass.cmdx_try(method)
           return @cmd_facets[method] = value.dup unless value.nil?
 
           default = options[:default]
-          value   = default.__cmdx_call
+          value   = default.cmdx_call
           @cmd_facets[method] = default.is_a?(Proc) ? value : value.dup
         end
       end
@@ -138,5 +95,4 @@ module CMDx
   end
 end
 
-# Extend all modules with CMDx utility methods
 Module.include(CMDx::CoreExt::ModuleExtensions)

data/lib/cmdx/core_ext/object.rb

@@ -2,151 +2,117 @@
 
 module CMDx
   module CoreExt
-    # Extensions to Object that provide CMDx-specific utility methods.
-    #
-    # ObjectExtensions adds safe method calling, conditional evaluation,
-    # and value yielding capabilities to all Ruby objects. These methods
-    # are prefixed with `__cmdx_` to avoid conflicts with existing methods.
-    #
-    # @example Safe method calling
-    #   object.__cmdx_try(:some_method)  # Returns nil if method doesn't exist
-    #   object.__cmdx_try(proc { expensive_calculation })  # Calls proc safely
-    #
-    # @example Conditional evaluation
-    #   object.__cmdx_eval(if: :valid?)       # True if object.valid? is true
-    #   object.__cmdx_eval(unless: :empty?)   # True unless object.empty? is true
-    #   object.__cmdx_eval(if: :valid?, unless: :processed?)  # Combined conditions
-    #
-    # @example Value yielding
-    #   object.__cmdx_yield(:name)           # Returns object.name if method exists, otherwise :name
-    #   object.__cmdx_yield(-> { compute })  # Executes lambda and returns result
-    #
-    # @see Task Tasks that use these object extensions
-    # @see Parameter Parameters that leverage object extensions
+    # Extensions for Ruby's Object class that provide flexible method calling and evaluation utilities.
+    # These extensions are automatically included in all objects when CMDx is loaded, providing
+    # safe method invocation, conditional evaluation, and dynamic yielding capabilities.
     module ObjectExtensions
 
-      # Store original respond_to? method before aliasing
-      alias __cmdx_respond_to? respond_to?
+      alias cmdx_respond_to? respond_to?
 
-      # Safely attempt to call a method or execute a proc on an object.
+      # Safely tries to call a method, evaluate a proc, or access a hash key.
+      # Provides flexible invocation that handles different types of callables gracefully.
       #
-      # This method provides safe method calling with fallback behavior.
-      # It handles method calls, proc execution, and hash key access gracefully.
+      # @param key [Symbol, String, Proc, Object] the method name, proc, or hash key to try
+      # @param args [Array] arguments to pass to the method or proc
       #
-      # @param key [Symbol, String, Proc] method name or callable to attempt
-      # @param args [Array] arguments to pass to the method/proc (passed via splat)
-      # @return [Object, nil] result of method call, proc execution, or nil if not possible
+      # @return [Object, nil] the result of the method call, proc evaluation, or hash access; nil if not found
       #
-      # @example Method calling
-      #   user.__cmdx_try(:name)              # => "John" or nil
-      #   user.__cmdx_try(:age, 25)           # => calls user.age(25) or nil
+      # @example Try calling a method
+      #   "hello".cmdx_try(:upcase) # => "HELLO"
+      #   "hello".cmdx_try(:missing) # => nil
       #
-      # @example Proc execution
-      #   user.__cmdx_try(-> { expensive_calc }) # => executes lambda
-      #   user.__cmdx_try(proc { |x| x * 2 }, 5) # => 10
+      # @example Try evaluating a proc
+      #   obj.cmdx_try(-> { self.class.name }) # => "String"
       #
-      # @example Hash access
-      #   hash = {name: "John"}
-      #   hash.__cmdx_try(:name)              # => "John"
-      def __cmdx_try(key, ...)
+      # @example Try accessing a hash key
+      #   {name: "John"}.cmdx_try(:name) # => "John"
+      def cmdx_try(key, *args, **kwargs, &)
         if key.is_a?(Proc)
           return instance_eval(&key) unless is_a?(Module) || key.inspect.include?("(lambda)")
 
-          key.call(...)
+          if key.arity.positive? && args.empty?
+            key.call(self, *args, **kwargs, &)
+          else
+            key.call(*args, **kwargs, &)
+          end
         elsif respond_to?(key, true)
-          send(key, ...)
+          send(key, *args, **kwargs, &)
         elsif is_a?(Hash)
-          __cmdx_fetch(key)
+          cmdx_fetch(key)
         end
       end
 
-      # Evaluate conditional options for execution control.
+      # Evaluates conditional options using :if and :unless logic.
+      # Supports both method names and procs for conditional evaluation.
       #
-      # This method evaluates :if and :unless conditions to determine
-      # whether something should proceed. Used extensively in callbacks
-      # and conditional parameter processing.
+      # @param options [Hash] evaluation options
+      # @option options [Symbol, Proc] :if condition that must be truthy
+      # @option options [Symbol, Proc] :unless condition that must be falsy
+      # @option options [Object] :default (true) default value when no conditions are specified
       #
-      # @param options [Hash] conditional options
-      # @option options [Symbol, Proc] :if condition that must be true
-      # @option options [Symbol, Proc] :unless condition that must be false
-      # @option options [Boolean] :default default value if no conditions (default: true)
-      # @return [Boolean] true if conditions are met
+      # @return [Boolean] true if conditions are met, false otherwise
       #
-      # @example Simple conditions
-      #   user.__cmdx_eval(if: :admin?)       # => true if user.admin? is true
-      #   user.__cmdx_eval(unless: :guest?)   # => true unless user.guest? is true
+      # @example Evaluate with if condition
+      #   user.cmdx_eval(if: :active?) # => true if user.active? is truthy
       #
-      # @example Combined conditions
-      #   user.__cmdx_eval(if: :active?, unless: :banned?)  # => active AND not banned
+      # @example Evaluate with unless condition
+      #   user.cmdx_eval(unless: :banned?) # => true if user.banned? is falsy
       #
-      # @example With procs
-      #   user.__cmdx_eval(if: -> { Time.now.monday? }) # => true if today is Monday
-      def __cmdx_eval(options = {})
+      # @example Evaluate with both conditions
+      #   user.cmdx_eval(if: :active?, unless: :banned?) # => true if active and not banned
+      def cmdx_eval(options = {})
         if options[:if] && options[:unless]
-          __cmdx_try(options[:if]) && !__cmdx_try(options[:unless])
+          cmdx_try(options[:if]) && !cmdx_try(options[:unless])
         elsif options[:if]
-          __cmdx_try(options[:if])
+          cmdx_try(options[:if])
         elsif options[:unless]
-          !__cmdx_try(options[:unless])
+          !cmdx_try(options[:unless])
         else
           options.fetch(:default, true)
         end
       end
 
-      # Yield a value by attempting to call it as a method or executing it.
+      # Yields or returns a value based on its type, with smart method calling.
+      # Handles symbols/strings as method names, procs/hashes via cmdx_try, and returns other values as-is.
       #
-      # This method provides intelligent value resolution - if the key is
-      # a method name and the object responds to it, call the method.
-      # Otherwise, try to execute it as a proc or return the value as-is.
+      # @param key [Symbol, String, Proc, Hash, Object] the value to yield or method to call
+      # @param args [Array] arguments to pass to method calls
       #
-      # @param key [Object] value to yield, method name, or callable
-      # @param args [Array] arguments to pass if calling method/proc (passed via splat)
-      # @return [Object] yielded value
+      # @return [Object] the result of method call, proc evaluation, or the value itself
       #
-      # @example Method yielding
-      #   user.__cmdx_yield(:name)           # => calls user.name if method exists, otherwise returns :name
-      #   user.__cmdx_yield("email")         # => calls user.email if method exists, otherwise returns "email"
+      # @example Yield a method call
+      #   "hello".cmdx_yield(:upcase) # => "HELLO"
       #
-      # @example Proc yielding
-      #   user.__cmdx_yield(-> { timestamp }) # => executes lambda
-      #   hash.__cmdx_yield({key: "value"})   # => tries hash access
+      # @example Yield a static value
+      #   obj.cmdx_yield("static") # => "static"
       #
-      # @example Direct values
-      #   user.__cmdx_yield(42)              # => 42
-      #   user.__cmdx_yield("literal")       # => "literal"
-      def __cmdx_yield(key, ...)
+      # @example Yield a proc
+      #   obj.cmdx_yield(-> { Time.now }) # => 2023-01-01 12:00:00 UTC
+      def cmdx_yield(key, ...)
         if key.is_a?(Symbol) || key.is_a?(String)
           return key unless respond_to?(key, true)
 
           send(key, ...)
         elsif is_a?(Hash) || key.is_a?(Proc)
-          __cmdx_try(key, ...)
+          cmdx_try(key, ...)
         else
           key
         end
       end
 
-      # Call an object if it responds to call, otherwise return itself.
-      #
-      # This method provides safe callable execution - if the object
-      # can be called (like a proc or lambda), call it with the given
-      # arguments. Otherwise, return the object unchanged.
+      # Invokes the object if it responds to :call, otherwise returns the object itself.
+      # Useful for handling both callable and non-callable objects uniformly.
       #
-      # @param args [Array] arguments to pass to call method (passed via splat)
-      # @return [Object] result of calling or the object itself
+      # @param args [Array] arguments to pass to the call method
       #
-      # @example Callable objects
-      #   proc = -> { "Hello" }
-      #   proc.__cmdx_call                   # => "Hello"
+      # @return [Object] the result of calling the object, or the object itself if not callable
       #
-      # @example Non-callable objects
-      #   string = "Hello"
-      #   string.__cmdx_call                 # => "Hello"
+      # @example Invoke a proc
+      #   proc { "hello" }.cmdx_call # => "hello"
       #
-      # @example With arguments
-      #   adder = ->(a, b) { a + b }
-      #   adder.__cmdx_call(2, 3)           # => 5
-      def __cmdx_call(...)
+      # @example Invoke a non-callable object
+      #   "hello".cmdx_call # => "hello"
+      def cmdx_call(...)
         return self unless respond_to?(:call)
 
         call(...)
@@ -156,5 +122,4 @@ module CMDx
   end
 end
 
-# Extend all objects with CMDx utility methods
 Object.include(CMDx::CoreExt::ObjectExtensions)

data/lib/cmdx/correlator.rb

@@ -1,205 +1,89 @@
 # frozen_string_literal: true
 
 module CMDx
-  ##
-  # Thread-safe correlation ID management for tracking related operations across request boundaries.
+  # Thread-local correlation ID management for tracing and tracking execution context.
   #
-  # The Correlator provides a simple, thread-local storage mechanism for managing correlation
-  # identifiers throughout the execution lifecycle. It enables tracing related operations
-  # across different tasks, workflows, and service boundaries within the same execution context.
-  #
-  # Correlation IDs are automatically used by CMDx runs when available, providing seamless
-  # request tracking without requiring explicit parameter passing between tasks.
-  #
-  # ## Thread Safety
-  #
-  # All correlation operations are thread-local, ensuring that different threads maintain
-  # separate correlation contexts without interference. This is essential for concurrent
-  # request processing in multi-threaded applications.
-  #
-  # ## Integration with CMDx Runs
-  #
-  # When a new CMDx::Chain is created, it automatically uses the current thread's correlation
-  # ID as its chain identifier if available, falling back to UUID generation if none exists.
-  #
-  # @example Basic correlation usage
-  #   CMDx::Correlator.id = "req-12345"
-  #   CMDx::Correlator.id  # => "req-12345"
-  #
-  #   # Chain automatically inherits correlation ID
-  #   result = ProcessOrderTask.call(order_id: 123)
-  #   result.chain.id  # => "req-12345"
-  #
-  # @example Block-based correlation context
-  #   CMDx::Correlator.use("workflow-operation-456") do
-  #     # All tasks within this block share the same correlation
-  #     ProcessOrderTask.call(order_id: 123)
-  #     SendEmailTask.call(user_id: 456)
-  #   end
-  #   # Correlation context is automatically restored
-  #
-  # @example Nested correlation contexts
-  #   CMDx::Correlator.use("parent-operation") do
-  #     CMDx::Correlator.use("child-operation") do
-  #       ProcessOrderTask.call(order_id: 123)
-  #       # Uses "child-operation" as correlation ID
-  #     end
-  #     # Restored to "parent-operation"
-  #     SendEmailTask.call(user_id: 456)
-  #   end
-  #
-  # @example Manual correlation management
-  #   # Set correlation ID for current thread
-  #   CMDx::Correlator.id = "manual-correlation"
-  #
-  #   # Check current correlation
-  #   current_id = CMDx::Correlator.id
-  #
-  #   # Clear correlation when done
-  #   CMDx::Correlator.clear
-  #
-  # @example Middleware integration pattern
-  #   class CorrelationMiddleware
-  #     def call(env)
-  #       correlation_id = env['HTTP_X_CORRELATION_ID'] || CMDx::Correlator.generate
-  #
-  #       CMDx::Correlator.use(correlation_id) do
-  #         @app.call(env)
-  #       end
-  #     end
-  #   end
-  #
-  # @see CMDx::Chain Chain execution context that inherits correlation IDs
-  # @since 1.0.0
+  # This module provides utilities for managing correlation IDs within thread-local storage,
+  # enabling request tracing and execution context tracking across task chains and workflows.
+  # Each thread maintains its own correlation ID that can be used to correlate related operations.
   module Correlator
 
-    ##
-    # Thread-local storage key for correlation identifiers.
-    #
-    # Uses a Symbol key to avoid potential conflicts with other thread-local
-    # variables and to ensure consistent access across the correlator methods.
-    #
-    # @return [Symbol] the thread-local storage key
     THREAD_KEY = :cmdx_correlation_id
 
     module_function
 
-    ##
-    # Generates a new UUID suitable for use as a correlation identifier.
-    #
-    # Creates a RFC 4122 compliant UUID using SecureRandom, providing a globally
-    # unique identifier suitable for distributed request tracing.
+    # Generates a new unique correlation ID using SecureRandom.
+    # Prefers UUID v7 when available, falls back to UUID v4.
     #
-    # @return [String] a new UUID string in standard format (e.g., "123e4567-e89b-12d3-a456-426614174000")
+    # @return [String] a new UUID string for use as correlation ID
     #
-    # @example Generating correlation IDs
-    #   id1 = CMDx::Correlator.generate  # => "018c2b95-b764-7615-a924-cc5b910ed1e5"
-    #   id2 = CMDx::Correlator.generate  # => "018c2b95-b765-7123-b456-dd7c920fe3a8"
-    #   id1 != id2  # => true
+    # @example Generate a new correlation ID
+    #   CMDx::Correlator.generate #=> "f47ac10b-58cc-4372-a567-0e02b2c3d479"
     def generate
+      return SecureRandom.uuid_v7 if SecureRandom.respond_to?(:uuid_v7)
+
       SecureRandom.uuid
     end
 
-    ##
-    # Retrieves the current thread's correlation identifier.
-    #
-    # Returns the correlation ID that was previously set for the current thread,
-    # or nil if no correlation ID has been established. This method is thread-safe
-    # and will not interfere with correlation IDs set in other threads.
+    # Retrieves the current thread's correlation ID.
     #
-    # @return [String, nil] the current correlation ID or nil if none is set
+    # @return [String, nil] the current correlation ID or nil if not set
     #
-    # @example Checking current correlation
-    #   CMDx::Correlator.id  # => nil (when none is set)
+    # @example Get current correlation ID
+    #   CMDx::Correlator.id #=> "f47ac10b-58cc-4372-a567-0e02b2c3d479"
     #
-    #   CMDx::Correlator.id = "test-correlation"
-    #   CMDx::Correlator.id  # => "test-correlation"
+    # @example When no correlation ID is set
+    #   CMDx::Correlator.id #=> nil
     def id
       Thread.current[THREAD_KEY]
     end
 
-    ##
-    # Sets the correlation identifier for the current thread.
-    #
-    # Assigns a correlation ID to the current thread's local storage, making it
-    # available for subsequent operations within the same thread context. The
-    # correlation ID will persist until explicitly changed or cleared.
+    # Sets the current thread's correlation ID.
     #
-    # @param value [String, #to_s] the correlation identifier to set
-    # @return [String] the assigned correlation identifier
+    # @param value [String, Symbol] the correlation ID to set
     #
-    # @example Setting correlation ID
-    #   CMDx::Correlator.id = "user-request-123"
-    #   CMDx::Correlator.id  # => "user-request-123"
+    # @return [String, Symbol] the value that was set
     #
-    # @example Type coercion
-    #   CMDx::Correlator.id = 12345
-    #   CMDx::Correlator.id  # => 12345 (stored as provided)
+    # @example Set correlation ID
+    #   CMDx::Correlator.id = "custom-trace-123"
+    #   CMDx::Correlator.id #=> "custom-trace-123"
     def id=(value)
       Thread.current[THREAD_KEY] = value
     end
 
-    ##
-    # Clears the correlation identifier for the current thread.
-    #
-    # Removes the correlation ID from the current thread's local storage,
-    # effectively resetting the correlation context. Subsequent calls to
-    # {#id} will return nil until a new correlation ID is set.
+    # Clears the current thread's correlation ID.
     #
     # @return [nil] always returns nil
     #
-    # @example Clearing correlation
-    #   CMDx::Correlator.id = "temporary-correlation"
-    #   CMDx::Correlator.id  # => "temporary-correlation"
-    #
+    # @example Clear correlation ID
     #   CMDx::Correlator.clear
-    #   CMDx::Correlator.id  # => nil
+    #   CMDx::Correlator.id #=> nil
     def clear
       Thread.current[THREAD_KEY] = nil
     end
 
-    ##
-    # Temporarily sets a correlation identifier for the duration of a block.
+    # Temporarily uses a correlation ID for the duration of a block.
+    # Restores the previous correlation ID after the block completes, even if an exception occurs.
     #
-    # Establishes a correlation context for the given block, automatically
-    # restoring the previous correlation ID when the block completes. This
-    # method is exception-safe and will restore the original context even
-    # if the block raises an error.
+    # @param value [String, Symbol] the correlation ID to use during block execution
     #
-    # This is the preferred method for managing correlation contexts as it
-    # ensures proper cleanup and supports nested correlation scopes.
+    # @return [Object] the result of the block execution
     #
-    # @param value [String, #to_s] the correlation identifier to use during block execution
-    # @yieldreturn [Object] the return value of the block
-    # @return [Object] the return value of the executed block
+    # @raise [TypeError] if value is not a String or Symbol
     #
-    # @example Basic usage
-    #   result = CMDx::Correlator.use("operation-123") do
-    #     ProcessOrderTask.call(order_id: 456)
+    # @example Use temporary correlation ID
+    #   CMDx::Correlator.use("temp-123") do
+    #     puts CMDx::Correlator.id  # => "temp-123"
+    #     # ... perform work ...
     #   end
-    #   # Correlation context is automatically restored
-    #
-    # @example Nested contexts
-    #   CMDx::Correlator.use("parent") do
-    #     CMDx::Correlator.id  # => "parent"
-    #
-    #     CMDx::Correlator.use("child") do
-    #       CMDx::Correlator.id  # => "child"
-    #     end
+    #   # Previous correlation ID is restored
     #
-    #     CMDx::Correlator.id  # => "parent" (restored)
-    #   end
-    #
-    # @example Exception safety
+    # @example With exception handling
     #   CMDx::Correlator.id = "original"
-    #
-    #   begin
-    #     CMDx::Correlator.use("temporary") do
-    #       raise StandardError, "something went wrong"
-    #     end
-    #   rescue StandardError
-    #     CMDx::Correlator.id  # => "original" (still restored)
+    #   CMDx::Correlator.use("temp") do
+    #     raise StandardError, "oops"
     #   end
+    #   # CMDx::Correlator.id is still "original"
     def use(value)
       unless value.is_a?(String) || value.is_a?(Symbol)
         raise TypeError,