musa-dsl 0.30.2 → 0.40.0

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

data/lib/musa-dsl/datasets/dataset.rb

@@ -1,3 +1,112 @@
+# Musical dataset framework for MusaDSL.
+#
+# The Datasets module provides a comprehensive framework for representing and transforming
+# musical events and data structures. It supports multiple representations (MIDI-style,
+# score-style, serialized formats) and conversions between them.
+#
+# ## Architecture
+#
+# The framework consists of several layers:
+#
+# ### 1. Event Types ({E})
+#
+# Hierarchy of event types defining absolute vs. delta encoding:
+#
+# - **{E}**: Base event module
+# - **{Abs}**: Absolute values (actual pitch, duration, etc.)
+# - **{Delta}**: Delta values (incremental changes)
+# - **{AbsI}**: Absolute indexed (array-based)
+# - **{AbsTimed}**: Absolute with time component
+# - **{AbsD}**: Absolute with duration
+# - **{DeltaD}**: Delta duration (absolute/delta/factor)
+#
+# ### 2. Data Structures
+#
+# Basic container types:
+#
+# - **{V}**: Value array - simple ordered values
+# - **{PackedV}**: Packed value hash - named key-value pairs
+# - **{P}**: Pitch series - alternating values and durations
+#
+# ### 3. Musical Datasets
+#
+# Domain-specific musical representations:
+#
+# - **{PS}**: Pitch series (from/to/duration for glissandi)
+# - **{PDV}**: Pitch/Duration/Velocity (MIDI-style representation)
+# - **{GDV}**: Grade/Duration/Velocity (score-style with scale degrees)
+# - **{GDVd}**: Grade/Duration/Velocity delta (incremental encoding)
+#
+# ### 4. Score Container
+#
+# - **{Score}**: Time-indexed container for musical events
+#
+# ## Basic Usage
+#
+#     # Create a packed value (hash)
+#     pv = { a: 1, b: 2, c: 3 }.extend(Musa::Datasets::PackedV)
+#
+#     # Convert to array
+#     v = pv.to_V([:c, :b, :a])  # => [3, 2, 1]
+#
+#     # Create pitch series
+#     p = [60, 4, 64, 8, 67].extend(Musa::Datasets::P)
+#     # [pitch, duration, pitch, duration, pitch]
+#
+#     # Convert to timed series
+#     timed = p.to_timed_serie
+#
+# ## Conversion Patterns
+#
+# The framework supports rich conversions:
+#
+# - PackedV ↔ V (hash to array and vice versa)
+# - P → PS (pitch series to glissando segments)
+# - PDV ↔ GDV (MIDI to score notation)
+# - GDV ↔ GDVd (absolute to delta encoding)
+# - GDV → Neuma (score notation string format)
+#
+# @example MIDI-style pitch/duration/velocity
+#   pdv = { pitch: 60, duration: 1.0, velocity: 64 }.extend(Musa::Datasets::PDV)
+#   pdv.base_duration = 1/4r
+#
+#   # Convert to score notation using scale
+#   scale = Musa::Scales::Scales.et12[440.0].major[60]
+#   gdv = pdv.to_gdv(scale)  # Uses scale degrees
+#
+# @example Score-style grade/duration/velocity
+#   gdv = { grade: 0, duration: 1.0, velocity: 0 }.extend(Musa::Datasets::GDV)
+#   gdv.base_duration = 1/4r
+#
+#   # Convert to MIDI using scale
+#   scale = Musa::Scales::Scales.et12[440.0].major[60]
+#   pdv = gdv.to_pdv(scale)  # Converts to MIDI pitches
+#
+# @example Delta encoding for compression
+#   scale = Musa::Scales::Scales.et12[440.0].major[60]
+#   gdv1 = { grade: 0, duration: 1.0, velocity: 0 }.extend(Musa::Datasets::GDV)
+#   gdv2 = { grade: 2, duration: 1.0, velocity: 1 }.extend(Musa::Datasets::GDV)
+#
+#   gdvd = gdv2.to_gdvd(scale, previous: gdv1)
+#   # => { delta_grade: 2, delta_velocity: 1 }
+#   # Duration unchanged, so omitted
+#
+# @example Score container
+#   score = Musa::Datasets::Score.new
+#   score.at(0, add: { grade: 0, duration: 1.0 }.extend(Musa::Datasets::GDV))
+#   score.at(1, add: { grade: 2, duration: 1.0 }.extend(Musa::Datasets::GDV))
+#
+# @see E Base event type
+# @see PDV MIDI-style representation
+# @see GDV Score-style representation
+# @see Score Event container
 module Musa::Datasets
+  # Base marker module for dataset types.
+  #
+  # Dataset is a simple marker module included by various dataset types
+  # to indicate they are part of the dataset framework.
+  #
+  # @see E Event base module
+  # @see P Pitch series dataset
   module Dataset; end
 end

data/lib/musa-dsl/datasets/delta-d.rb

@@ -1,9 +1,87 @@
 require_relative 'e'
 
 module Musa::Datasets
+  # Delta events with flexible duration encoding.
+  #
+  # DeltaD (Delta Duration) extends {Delta} events with three different ways to
+  # specify duration changes in delta-encoded sequences. This provides flexibility
+  # for efficient encoding of musical sequences.
+  #
+  # ## Duration Encoding Modes
+  #
+  # **:abs_duration** - Absolute duration override
+  #
+  # Sets duration to an absolute value, regardless of previous duration.
+  # Use when duration changes to a completely different value.
+  #
+  #     { abs_duration: 2.0 }
+  #     # Sets duration to 2.0, ignoring previous
+  #
+  # **:delta_duration** - Incremental duration change
+  #
+  # Adds or subtracts from the previous duration value.
+  # Use for small adjustments to duration.
+  #
+  #     { delta_duration: 0.5 }   # Add 0.5 to previous
+  #     { delta_duration: -0.25 } # Subtract 0.25 from previous
+  #
+  # **:factor_duration** - Multiplicative duration factor
+  #
+  # Multiplies previous duration by a factor.
+  # Use for proportional changes (doubling, halving, etc.).
+  #
+  #     { factor_duration: 2 }    # Double previous duration
+  #     { factor_duration: 0.5 }  # Half previous duration
+  #
+  # ## Natural Keys
+  #
+  # - **:abs_duration**: Absolute duration value
+  # - **:delta_duration**: Duration increment/decrement
+  # - **:factor_duration**: Duration multiplication factor
+  #
+  # Only one duration key should be present at a time.
+  #
+  # ## Usage in Delta Encoding
+  #
+  # Used by {GDVd} for efficient delta encoding of musical sequences:
+  #
+  # @example Different duration encoding modes
+  #   previous = { duration: 1.0 }
+  #
+  #   # Absolute: set to specific value
+  #   delta1 = { abs_duration: 2.0 }.extend(DeltaD)
+  #   # Result: duration becomes 2.0
+  #
+  #   # Delta: add to previous
+  #   delta2 = { delta_duration: 0.5 }.extend(DeltaD)
+  #   # Result: duration becomes 1.5 (was 1.0)
+  #
+  #   # Factor: multiply previous
+  #   delta3 = { factor_duration: 2 }.extend(DeltaD)
+  #   # Result: duration becomes 2.0 (was 1.0)
+  #
+  # @example Neuma notation representation
+  #   # Absolute duration
+  #   { abs_duration: 1.5 } => "1.5"
+  #
+  #   # Delta duration
+  #   { delta_duration: 0.5 }  => "+0.5"
+  #   { delta_duration: -0.5 } => "-0.5"
+  #
+  #   # Factor duration
+  #   { factor_duration: 2 } => "*2"
+  #
+  # @see Delta Parent delta module
+  # @see GDVd Grade/Duration/Velocity delta encoding
+  # @see AbsD Absolute duration events
   module DeltaD
     include Delta
 
+    # Natural keys for delta duration encoding.
+    #
+    # Only one of these keys should be present in a delta event.
+    #
+    # @return [Array<Symbol>] natural duration keys
     NaturalKeys = [:abs_duration, # absolute duration
                    :delta_duration, # incremental duration
                    :factor_duration # multiplicative factor duration