musa-dsl 0.30.2 → 0.41.0

data/lib/musa-dsl/core-ext/hashify.rb

@@ -1,8 +1,98 @@
+require_relative 'extension'
 require_relative 'deep-copy'
 
 module Musa
   module Extension
+    # Refinement that converts objects, arrays, and hashes into hashes with specified keys.
+    #
+    # This refinement is crucial for normalizing parameters in the DSL, especially when
+    # dealing with musical events that can be specified in multiple formats (positional,
+    # hash-based, or mixed).
+    #
+    # ## Core Behavior
+    #
+    # - **Object**: Creates hash mapping all keys to the same value
+    # - **Array**: Maps keys to array elements in order (consuming array)
+    # - **Hash**: Filters and reorders according to specified keys
+    # - **Preserves singleton class modules** on hash results
+    #
+    # ## Use Cases
+    #
+    # - Converting positional parameters to named parameters
+    # - Normalizing mixed parameter formats in musical events
+    # - Extracting specific keys from larger hashes
+    # - Providing defaults for missing event attributes
+    #
+    # @example Basic object hashification
+    #   using Musa::Extension::Hashify
+    #
+    #   100.hashify(keys: [:velocity, :duration])
+    #   # => { velocity: 100, duration: 100 }
+    #
+    # @example Array to hash
+    #   using Musa::Extension::Hashify
+    #
+    #   [60, 100, 0.5].hashify(keys: [:pitch, :velocity, :duration])
+    #   # => { pitch: 60, velocity: 100, duration: 0.5 }
+    #
+    # @example Hash filtering and reordering
+    #   using Musa::Extension::Hashify
+    #
+    #   { pitch: 60, velocity: 100, channel: 0, duration: 1 }
+    #     .hashify(keys: [:pitch, :velocity])
+    #   # => { pitch: 60, velocity: 100 }
+    #
+    # @example With defaults
+    #   using Musa::Extension::Hashify
+    #
+    #   [60].hashify(keys: [:pitch, :velocity, :duration], default: nil)
+    #   # => { pitch: 60, velocity: nil, duration: nil }
+    #
+    # @example Musical event normalization
+    #   using Musa::Extension::Hashify
+    #
+    #   # User provides just a pitch
+    #   60.hashify(keys: [:pitch, :velocity], default: 64)
+    #   # => { pitch: 60, velocity: 64 }
+    #
+    #   # User provides array [pitch, velocity, duration]
+    #   [62, 90, 0.5].hashify(keys: [:pitch, :velocity, :duration])
+    #   # => { pitch: 62, velocity: 90, duration: 0.5 }
+    #
+    # @see Musa::Datasets Hash-based event structures
+    # @note This refinement must be activated with `using Musa::Extension::Hashify`
+    # @note Singleton class modules (dataset extensions) are preserved on hash results
+    #
+    # ## Methods Added
+    #
+    # ### Object
+    # - {Object#hashify} - Creates a hash mapping all specified keys to this object's value
+    #
+    # ### Array
+    # - {Array#hashify} - Maps array elements to hash keys in order, consuming the array
+    #
+    # ### Hash
+    # - {Hash#hashify} - Filters and reorders hash to include only specified keys, preserving modules
     module Hashify
+      # @!method hashify(keys:, default: nil)
+      #   Creates a hash mapping all specified keys to this object's value.
+      #
+      #   Useful for broadcasting a single value across multiple attributes.
+      #   Nil objects can be replaced with a default value.
+      #
+      #   @note This method is added to Object via refinement. Requires `using Musa::Extension::Hashify`.
+      #
+      #   @param keys [Array<Symbol>] keys for the resulting hash.
+      #   @param default [Object, nil] value to use if self is nil.
+      #
+      #   @return [Hash] hash with all keys mapped to self (or default if nil).
+      #
+      #   @example Single value to multiple keys
+      #     using Musa::Extension::Hashify
+      #     127.hashify(keys: [:velocity, :pressure])
+      #     # => { velocity: 127, pressure: 127 }
+      class ::Object; end
+
       refine Object do
         def hashify(keys:, default: nil)
           keys.collect do |key|
@@ -16,6 +106,36 @@ module Musa
         end
       end
 
+      # @!method hashify(keys:, default: nil)
+      #   Maps array elements to hash keys in order, consuming the array.
+      #
+      #   Elements are assigned to keys sequentially. If the array has fewer elements
+      #   than keys, remaining keys get nil (or default). The array is cloned before
+      #   consumption, so the original is unchanged.
+      #
+      #   @note This method is added to Array via refinement. Requires `using Musa::Extension::Hashify`.
+      #
+      #   @param keys [Array<Symbol>] keys for the resulting hash (in order).
+      #   @param default [Object, nil] value for keys without corresponding array elements.
+      #
+      #   @return [Hash] hash with keys mapped to array elements in order.
+      #
+      #   @example Basic array mapping
+      #     using Musa::Extension::Hashify
+      #     [60, 100, 0.25].hashify(keys: [:pitch, :velocity, :duration])
+      #     # => { pitch: 60, velocity: 100, duration: 0.25 }
+      #
+      #   @example Fewer elements than keys
+      #     using Musa::Extension::Hashify
+      #     [60, 100].hashify(keys: [:pitch, :velocity, :duration], default: nil)
+      #     # => { pitch: 60, velocity: 100, duration: nil }
+      #
+      #   @example More elements than keys (extras ignored)
+      #     using Musa::Extension::Hashify
+      #     [60, 100, 0.5, :ignored].hashify(keys: [:pitch, :velocity])
+      #     # => { pitch: 60, velocity: 100 }
+      class ::Array; end
+
       refine Array do
         def hashify(keys:, default: nil)
           values = clone
@@ -23,10 +143,51 @@ module Musa
             value = values.shift
             [ key,
               value.nil? ? default : value ]
-          end.to_hash
+          end.to_h
         end
       end
 
+      # @!method hashify(keys:, default: nil)
+      #   Filters and reorders hash to include only specified keys, preserving modules.
+      #
+      #   Creates a new hash with only the requested keys, in the order specified.
+      #   Missing keys get nil (or default). Singleton class modules (like dataset
+      #   extensions) are copied to the result.
+      #
+      #   @note This method is added to Hash via refinement. Requires `using Musa::Extension::Hashify`.
+      #
+      #   @param keys [Array<Symbol>] keys to include in result (order matters).
+      #   @param default [Object, nil] value for keys not present in source hash.
+      #
+      #   @return [Hash] new hash with specified keys, preserving singleton modules.
+      #
+      #   @example Filtering keys
+      #     using Musa::Extension::Hashify
+      #     { pitch: 60, velocity: 100, channel: 0 }
+      #       .hashify(keys: [:pitch, :velocity])
+      #     # => { pitch: 60, velocity: 100 }
+      #
+      #   @example Reordering keys
+      #     using Musa::Extension::Hashify
+      #     { velocity: 100, pitch: 60 }
+      #       .hashify(keys: [:pitch, :velocity])
+      #     # => { pitch: 60, velocity: 100 }
+      #
+      #   @example Adding missing keys with default
+      #     using Musa::Extension::Hashify
+      #     { pitch: 60 }
+      #       .hashify(keys: [:pitch, :velocity], default: 80)
+      #     # => { pitch: 60, velocity: 80 }
+      #
+      #   @example Preserving dataset modules
+      #     using Musa::Extension::Hashify
+      #     event = { pitch: 60, velocity: 100 }.extend(Musa::Datasets::AbsI)
+      #     event.hashify(keys: [:pitch, :velocity])
+      #     # Result also extended with AbsI
+      #
+      #   @note Singleton class modules are preserved via DeepCopy.copy_singleton_class_modules
+      class ::Hash; end
+
       refine Hash do
         def hashify(keys:, default: nil)
           keys.collect do |key|

data/lib/musa-dsl/core-ext/inspect-nice.rb

@@ -1,6 +1,89 @@
+require_relative 'extension'
+
 module Musa
   module Extension
+    # Refinements that provide more readable inspect/to_s output for Hash and Rational.
+    #
+    # These refinements improve readability of log output and debugging, especially
+    # important when working with musical data that heavily uses Rationals for timing
+    # and Hashes for event parameters.
+    #
+    # ## Changes
+    #
+    # - **Hash**: Compact syntax with symbol keys shown as `key: value`
+    # - **Rational**: Musical-friendly format like `3+1/4r` instead of `(13/4)`
+    # - **Configurable**: Rational display can switch between simple and detailed modes
+    #
+    # ## Use Cases
+    #
+    # - Improving log readability in musical applications
+    # - Debugging DSL expressions with cleaner output
+    # - Displaying musical time values (bars, durations) naturally
+    #
+    # @example Hash formatting
+    #   using Musa::Extension::InspectNice
+    #
+    #   { pitch: 60, velocity: 100 }.inspect
+    #   # => "{ pitch: 60, velocity: 100 }"
+    #   # Instead of: "{:pitch=>60, :velocity=>100}"
+    #
+    # @example Rational formatting (detailed mode)
+    #   using Musa::Extension::InspectNice
+    #
+    #   (5/4r).inspect       # => "1+1/4r"
+    #   (3/2r).inspect       # => "1+1/2r"
+    #   (2/1r).inspect       # => "2r"
+    #   (-3/4r).inspect      # => "-3/4r"
+    #
+    # @example Rational formatting (simple mode)
+    #   using Musa::Extension::InspectNice
+    #
+    #   Rational.to_s_as_inspect = false
+    #   (5/4r).to_s          # => "5/4"
+    #   (2/1r).to_s          # => "2"
+    #
+    # @see Musa::Logger::Logger Uses these refinements for cleaner logs
+    # @note These refinements must be activated with `using Musa::Extension::InspectNice`
+    #
+    # ## Methods Added
+    #
+    # ### Hash
+    # - {Hash#inspect} - Compact, readable inspect output with symbol-key shorthand
+    # - {Hash#to_s} - Aliases to_s to inspect for consistency
+    #
+    # ### Rational (singleton class)
+    # - {Rational.to_s_as_inspect} - Controls whether Rational#to_s uses inspect format
+    #
+    # ### Rational
+    # - {Rational#inspect} - Musical-friendly inspect output for Rational numbers
+    # - {Rational#to_s} - String representation controlled by Rational.to_s_as_inspect
     module InspectNice
+      # @!method inspect
+      #   Provides compact, readable inspect output with symbol-key shorthand.
+      #
+      #   Symbol keys are displayed as `key: value` (Ruby 2.0+ syntax) instead of
+      #   `:key => value`. String/other keys use the fat arrow syntax.
+      #
+      #   @note This method is added to Hash via refinement. Requires `using Musa::Extension::InspectNice`.
+      #
+      #   @return [String] compact hash representation.
+      #
+      #   @example Mixed keys
+      #     using Musa::Extension::InspectNice
+      #     { pitch: 60, 'name' => 'C4' }.inspect
+      #     # => "{ pitch: 60, 'name' => 'C4' }"
+      class ::Hash; end
+
+      # @!method to_s
+      #   Aliases to_s to inspect for consistency.
+      #
+      #   @note This method is added to Hash via refinement. Requires `using Musa::Extension::InspectNice`.
+      #
+      #   @return [String] compact hash representation.
+      #
+      #   @see Hash#inspect
+      class ::Hash; end
+
       refine Hash do
         def inspect
           all = collect { |key, value| [', ', key.is_a?(Symbol) ? key.to_s + ': ' : key.inspect + ' => ', value.inspect] }.flatten
@@ -12,10 +95,81 @@ module Musa
         alias to_s inspect
       end
 
+      # Adds configuration attribute to Rational singleton class.
+      #
+      # This allows global control of Rational#to_s behavior.
+      #
+      # @!attribute [rw] to_s_as_inspect
+      #   Controls whether Rational#to_s uses inspect format.
+      #
+      #   When true: to_s displays detailed format (e.g., "1+1/4r")
+      #   When false/nil: to_s displays simple format (e.g., "5/4")
+      #
+      #   @note This attribute is added to Rational's singleton class via refinement. Requires `using Musa::Extension::InspectNice`.
+      #
+      #   @return [Boolean, nil] current mode
+      #
+      #   @example Switching modes
+      #     using Musa::Extension::InspectNice
+      #     Rational.to_s_as_inspect = true
+      #     (5/4r).to_s  # => "1+1/4r"
+      class ::Rational; end
+
       refine Rational.singleton_class do
         attr_accessor :to_s_as_inspect
       end
 
+      # @!method inspect(simple: nil)
+      #   Provides musical-friendly inspect output for Rational numbers.
+      #
+      #   Two modes:
+      #   - **Simple**: Just numerator/denominator (e.g., "5/4", "2")
+      #   - **Detailed**: Mixed number with 'r' suffix (e.g., "1+1/4r", "2r")
+      #
+      #   The detailed format is particularly useful for musical time values,
+      #   making expressions like "3+1/2r" (3.5 bars) immediately readable.
+      #
+      #   @note This method is added to Rational via refinement. Requires `using Musa::Extension::InspectNice`.
+      #
+      #   @param simple [Boolean, nil] if true, uses simple format; if false/nil, uses detailed.
+      #
+      #   @return [String] formatted rational.
+      #
+      #   @example Detailed format (default for inspect)
+      #     using Musa::Extension::InspectNice
+      #     (5/4r).inspect            # => "1+1/4r"
+      #     (7/4r).inspect            # => "1+3/4r"
+      #     (-3/2r).inspect           # => "-1-1/2r"
+      #     (8/4r).inspect            # => "2r"
+      #     (3/4r).inspect            # => "3/4r"
+      #
+      #   @example Simple format
+      #     using Musa::Extension::InspectNice
+      #     (5/4r).inspect(simple: true)   # => "5/4"
+      #     (8/4r).inspect(simple: true)   # => "2"
+      class ::Rational; end
+
+      # @!method to_s
+      #   Provides string representation, format controlled by Rational.to_s_as_inspect.
+      #
+      #   Delegates to #inspect with the appropriate simple flag based on the
+      #   global Rational.to_s_as_inspect setting.
+      #
+      #   @note This method is added to Rational via refinement. Requires `using Musa::Extension::InspectNice`.
+      #
+      #   @return [String] formatted rational.
+      #
+      #   @example When to_s_as_inspect is true
+      #     using Musa::Extension::InspectNice
+      #     Rational.to_s_as_inspect = true
+      #     (5/4r).to_s  # => "1+1/4r"
+      #
+      #   @example When to_s_as_inspect is false/nil
+      #     using Musa::Extension::InspectNice
+      #     Rational.to_s_as_inspect = false
+      #     (5/4r).to_s  # => "5/4"
+      class ::Rational; end
+
       refine Rational do
         def inspect(simple: nil)
           value = self.abs

data/lib/musa-dsl/core-ext/smart-proc-binder.rb

@@ -1,17 +1,75 @@
+require_relative 'extension'
+
 module Musa
   module Extension
+    # Module providing smart parameter binding for Proc objects.
+    #
+    # SmartProcBinder analyzes a Proc's parameter signature and intelligently
+    # matches provided arguments to expected parameters, handling both positional
+    # and keyword arguments with proper rest parameter support.
+    #
+    # @see Musa::Extension::With Uses SmartProcBinder for parameter management
     module SmartProcBinder
+      # Wrapper for Proc objects that provides intelligent parameter matching and binding.
+      #
+      # This class introspects a Proc's parameter list and provides methods to:
+      # - Determine which parameters the Proc accepts
+      # - Filter provided arguments to match the Proc's signature
+      # - Call the Proc with properly matched arguments
+      # - Optionally rescue and handle exceptions
+      #
+      # ## Parameter Types Handled
+      #
+      # - **:req, :opt**: Required and optional positional parameters
+      # - **:rest**: Splat parameter (*args)
+      # - **:key, :keyreq**: Optional and required keyword parameters
+      # - **:keyrest**: Double splat parameter (**kwargs)
+      #
+      # ## Use Cases
+      #
+      # - DSL methods that need flexible parameter passing
+      # - Builder patterns with variable block signatures
+      # - Wrapper methods that forward arguments intelligently
+      # - Error handling for DSL block execution
+      #
+      # @example Basic usage
+      #   block = proc { |a, b, c:| [a, b, c] }
+      #   binder = SmartProcBinder.new(block)
+      #
+      #   binder.call(1, 2, 3, 4, c: 5, d: 6)
+      #   # => [1, 2, 5]
+      #   # Only passes parameters that match signature
+      #
+      # @example With rescue handling
+      #   error_handler = proc { |e| puts "Error: #{e.message}" }
+      #   binder = SmartProcBinder.new(block, on_rescue: error_handler)
+      #
+      #   binder.call(invalid_args)  # Calls error_handler instead of raising
+      #
+      # @example Checking parameter support
+      #   binder.key?(:pitch)  # => true/false
+      #   binder.has_key?(:velocity)  # => true/false
       class SmartProcBinder
+        # Creates a new SmartProcBinder wrapping the given block.
+        #
+        # Introspects the block's parameters and categorizes them for later matching.
+        #
+        # @param block [Proc] the proc/block to wrap.
+        # @param on_rescue [Proc, nil] optional error handler called with exception
+        #   if block execution fails.
         def initialize(block, on_rescue: nil)
           @block = block
           @on_rescue = on_rescue
 
+          # Track keyword parameters by name
           @key_parameters = {}
           @has_key_rest = false
 
+          # Track positional parameter count
           @value_parameters_count = 0
           @has_value_rest = false
 
+          # Introspect block's parameter signature
           block.parameters.each do |parameter|
             @key_parameters[parameter[1]] = nil if parameter[0] == :key || parameter[0] == :keyreq
             @has_key_rest = true if parameter[0] == :keyrest
@@ -21,18 +79,36 @@ module Musa
           end
         end
 
+        # Returns the wrapped Proc.
+        #
+        # @return [Proc] the original block.
         def proc
           @block
         end
 
+        # Returns the parameter signature of the wrapped Proc.
+        #
+        # @return [Array<Array>] array of [type, name] pairs describing parameters.
+        # @example
+        #   proc { |a, b, c:| }.parameters  # => [[:req, :a], [:req, :b], [:key, :c]]
         def parameters
           @block.parameters
         end
 
+        # Calls the wrapped Proc with smart parameter matching.
+        #
+        # @param value_parameters [Array] positional arguments.
+        # @param key_parameters [Hash] keyword arguments.
+        # @param block [Proc, nil] block to pass to wrapped Proc.
+        #
+        # @return [Object] result of calling the wrapped Proc.
         def call(*value_parameters, **key_parameters, &block)
           _call value_parameters, key_parameters, block
         end
 
+        # Internal call implementation with error handling.
+        #
+        # @api private
         def _call(value_parameters, key_parameters = {}, block = nil)
           if @on_rescue
             begin
@@ -63,16 +139,43 @@ module Musa
           end
         end
 
+        # Checks if the wrapped Proc accepts a specific keyword parameter.
+        #
+        # Returns true if the Proc has a keyword parameter with the given name,
+        # or if it has a **kwargs rest parameter that accepts any keyword.
+        #
+        # @param key [Symbol] keyword parameter name to check.
+        #
+        # @return [Boolean] true if key is accepted, false otherwise.
+        #
+        # @example
+        #   proc { |a:, b:, **rest| }.key?(:a)       # => true
+        #   proc { |a:, b:, **rest| }.key?(:unknown) # => true (has **rest)
+        #   proc { |a:, b:| }.key?(:unknown)         # => false
         def key?(key)
           @has_key_rest || @key_parameters.include?(key)
         end
 
         alias_method :has_key?, :key?
 
+        # Filters arguments to match the Proc's signature.
+        #
+        # @param value_parameters [Array] positional arguments to filter.
+        # @param key_parameters [Hash] keyword arguments to filter.
+        #
+        # @return [Array<Array, Hash>] tuple of [filtered_positionals, filtered_keywords].
         def apply(*value_parameters, **key_parameters)
           _apply(value_parameters, key_parameters)
         end
 
+        # Internal implementation of argument filtering.
+        #
+        # Logic:
+        # - Positional: takes first N values (or all if *rest present)
+        # - Keywords: includes only expected keys (or all if **rest present)
+        # - Pads positional with nils if needed
+        #
+        # @api private
         def _apply(value_parameters, key_parameters)
           value_parameters ||= []
           key_parameters ||= {}
@@ -99,6 +202,20 @@ module Musa
           return values_result, hash_result
         end
 
+        # Returns a string representation of the SmartProcBinder for debugging.
+        #
+        # Shows the wrapped Proc's parameter signature and internal state, making
+        # it easy to understand what parameters the binder expects and how it will
+        # match arguments.
+        #
+        # @return [String] formatted string showing parameters and configuration.
+        #
+        # @example Inspecting binder state
+        #   block = proc { |a, b, c:, **rest| }
+        #   binder = SmartProcBinder.new(block)
+        #   puts binder.inspect
+        #   # => "SmartProcBinder: parameters = [[:req, :a], [:req, :b], [:key, :c], [:keyrest, :rest]]
+        #   #     key_parameters = {:c=>nil} has_rest = true"
         def inspect
           "SmartProcBinder: parameters = #{parameters} key_parameters = #{@key_parameters} has_rest = #{@has_key_rest}"
         end

data/lib/musa-dsl/core-ext/with.rb

@@ -1,28 +1,142 @@
+require_relative 'extension'
 require_relative 'smart-proc-binder'
 
 module Musa
   module Extension
+    # Module providing the `with` method for flexible DSL block execution.
+    #
+    # The `with` method is a cornerstone of Musa DSL's builder pattern, allowing
+    # objects to execute blocks in either the object's context (for DSL-style
+    # configuration) or the caller's context (for traditional Ruby blocks).
+    #
+    # ## Context Switching Logic
+    #
+    # The method intelligently determines which context to use based on:
+    # 1. The `keep_block_context` parameter (explicit control)
+    # 2. Block parameters (implicit control via `_` parameter)
+    # 3. Whether parameters are passed to the block
+    #
+    # ## Modes of Operation
+    #
+    # - **DSL mode** (`instance_eval`): Block executes in object's context
+    #   - Used when: no parameters, no `keep_block_context`, no `_` parameter
+    #   - Enables: direct access to object's instance variables and methods
+    #
+    # - **Caller context mode** (`call` with self as `_`): Block keeps its context
+    #   - Used when: block has `_` parameter, or `keep_block_context: true`
+    #   - Enables: access to both contexts (object via `_`, caller's scope naturally)
+    #
+    # - **Hybrid mode** (`instance_exec`): Block in object context with parameters
+    #   - Used when: parameters provided but `keep_block_context` not set
+    #   - Enables: DSL-style access plus explicit parameters
+    #
+    # ## Use Cases
+    #
+    # - Builder pattern DSL methods
+    # - Configuration blocks that need object context
+    # - Flexible API supporting both DSL and traditional Ruby styles
+    # - Initializers that configure objects via blocks
+    #
+    # @example DSL mode (instance_eval)
+    #   class Builder
+    #     include Musa::Extension::With
+    #
+    #     def initialize(&block)
+    #       @items = []
+    #       with(&block) if block
+    #     end
+    #
+    #     def add(item)
+    #       @items << item
+    #     end
+    #   end
+    #
+    #   builder = Builder.new do
+    #     add :foo
+    #     add :bar
+    #   end
+    #   # Block has direct access to #add method
+    #
+    # @example Caller context with _ parameter
+    #   external_var = 42
+    #
+    #   Builder.new do |_|
+    #     _.add :foo
+    #     puts external_var  # Can access caller's variables
+    #   end
+    #   # Block keeps caller's context, object accessed via _
+    #
+    # @example With parameters
+    #   class Builder
+    #     def initialize(name, &block)
+    #       @name = name
+    #       with(name, &block) if block
+    #     end
+    #   end
+    #
+    #   Builder.new('test') do |name|
+    #     # Has access to object's context AND receives name parameter
+    #     puts @name  # Works
+    #     puts name   # Also works
+    #   end
+    #
+    # @example Explicit keep_block_context
+    #   Builder.new do |obj|
+    #     obj.add :item
+    #     # Block explicitly keeps caller's context
+    #   end
+    #
+    # @see SmartProcBinder Used internally for parameter management
+    # @see Musa::Datasets DSL builder methods use this extensively
     module With
+      # Executes a block with flexible context and parameter handling.
+      #
+      # @param value_parameters [Array] positional parameters to pass to block.
+      # @param keep_block_context [Boolean, nil] explicit control of context switching:
+      #   - `true`: always keep caller's context
+      #   - `false`: always use object's context
+      #   - `nil`: auto-detect based on `_` parameter
+      # @param key_parameters [Hash] keyword parameters to pass to block.
+      # @param block [Proc] block to execute.
+      #
+      # @return [Object] result of block execution.
+      #
+      # @note The `_` parameter is special: when present, it signals "keep caller's context"
+      #   and receives `self` (the object) as its value.
+      # @note Uses SmartProcBinder internally to handle parameter matching.
       def with(*value_parameters, keep_block_context: nil, **key_parameters, &block)
+        # Wrap block in SmartProcBinder for parameter introspection and management
         smart_block = Musa::Extension::SmartProcBinder::SmartProcBinder.new(block)
 
+        # Check if first parameter is _ (underscore), which signals "keep caller's context"
         send_self_as_underscore_parameter = smart_block.parameters[0][1] == :_ unless smart_block.parameters.empty?
 
+        # Determine effective context mode:
+        # 1. Use explicit keep_block_context if provided
+        # 2. Otherwise, use _ parameter presence as signal
+        # 3. Default to false (use object's context)
         effective_keep_block_context = keep_block_context
         effective_keep_block_context = send_self_as_underscore_parameter if effective_keep_block_context.nil?
         effective_keep_block_context = false if effective_keep_block_context.nil?
 
+        # Match provided parameters to block's expected parameters
         effective_value_parameters, effective_key_parameters = smart_block._apply(value_parameters, key_parameters)
 
+        # Execute block in appropriate context
         if effective_keep_block_context
+          # Keep caller's context: call block normally
           if send_self_as_underscore_parameter
+            # Pass self as first parameter (the _ parameter)
             smart_block.call(self, *effective_value_parameters, **effective_key_parameters)
           else
+            # Just pass the effective parameters
             smart_block.call(*effective_value_parameters, **effective_key_parameters)
           end
         elsif effective_value_parameters.empty? && effective_key_parameters.empty?
+          # DSL mode: no parameters, execute in object's context
           instance_eval &block
         else
+          # Hybrid mode: execute in object's context with parameters
           instance_exec *effective_value_parameters, **effective_key_parameters, &block
         end
       end