musa-dsl 0.40.0 → 0.42.0

data/docs/subsystems/music.md

@@ -20,10 +20,54 @@ The **Scales** module provides hierarchical access to musical scales with multip
 - `:et12` (EquallyTempered12ToneScaleSystem): 12-tone equal temperament (default)
 
 **Available scale kinds in et12:**
-- `:major` - Major scale (Ionian mode)
-- `:minor` - Natural minor scale (Aeolian mode)
-- `:minor_harmonic` - Harmonic minor scale (raised 7th degree)
-- `:chromatic` - Chromatic scale (all 12 semitones)
+
+*Core scales:*
+- `:major` - Major scale (Ionian mode) - 7 notes
+- `:minor` - Natural minor scale (Aeolian mode) - 7 notes
+- `:minor_harmonic` - Harmonic minor scale (raised 7th) - 7 notes
+- `:major_harmonic` - Harmonic major scale (lowered 6th) - 7 notes
+- `:chromatic` - Chromatic scale (all 12 semitones) - 12 notes
+
+*Greek/church modes:*
+- `:dorian` - Dorian mode (minor with major 6th) - 7 notes
+- `:phrygian` - Phrygian mode (minor with minor 2nd) - 7 notes
+- `:lydian` - Lydian mode (major with augmented 4th) - 7 notes
+- `:mixolydian` - Mixolydian mode (major with minor 7th) - 7 notes
+- `:locrian` - Locrian mode (diminished 5th and minor 2nd) - 7 notes
+
+*Pentatonic scales:*
+- `:pentatonic_major` - Major pentatonic (no 4th or 7th) - 5 notes
+- `:pentatonic_minor` - Minor pentatonic (no 2nd or 6th) - 5 notes
+
+*Blues scales:*
+- `:blues` - Blues scale (minor pentatonic + b5 blue note) - 6 notes
+- `:blues_major` - Major blues scale (major pentatonic + b3 blue note) - 6 notes
+
+*Symmetric scales:*
+- `:whole_tone` - Whole tone scale (all whole steps) - 6 notes
+- `:diminished_hw` - Diminished half-whole (octatonic) - 8 notes
+- `:diminished_wh` - Diminished whole-half (dominant diminished) - 8 notes
+
+*Melodic minor modes:*
+- `:minor_melodic` - Melodic minor (jazz minor) - 7 notes
+- `:dorian_b2` - Dorian b2 / Phrygian #6 - 7 notes
+- `:lydian_augmented` - Lydian augmented (#4, #5) - 7 notes
+- `:lydian_dominant` - Lydian dominant / Bartók scale (#4, b7) - 7 notes
+- `:mixolydian_b6` - Mixolydian b6 / Hindu scale - 7 notes
+- `:locrian_sharp2` - Locrian #2 / Half-diminished scale - 7 notes
+- `:altered` - Altered / Super Locrian (all tensions altered) - 7 notes
+
+*Ethnic/exotic scales:*
+- `:double_harmonic` - Double harmonic / Byzantine (two augmented 2nds) - 7 notes
+- `:hungarian_minor` - Hungarian minor / Gypsy minor (#4, raised 7th) - 7 notes
+- `:phrygian_dominant` - Phrygian dominant / Spanish Phrygian (b2, major 3rd) - 7 notes
+- `:neapolitan_minor` - Neapolitan minor (harmonic minor with b2) - 7 notes
+- `:neapolitan_major` - Neapolitan major (melodic minor with b2) - 7 notes
+
+*Bebop scales:*
+- `:bebop_dominant` - Bebop dominant (Mixolydian + major 7th passing) - 8 notes
+- `:bebop_major` - Bebop major (major + #5 passing) - 8 notes
+- `:bebop_minor` - Bebop minor (Dorian + major 7th passing) - 8 notes
 
 ## Chords System
 
@@ -79,8 +123,8 @@ c_major[:V]    # => Dominant (G)
 pitch = c_major.tonic.pitch   # => 60
 
 # Navigate with octaves
-note = c_major[2].octave(1)  # E in octave 1
-pitch_with_octave = note.pitch     # => 76
+note = c_major[2].at_octave(1)  # E transposed up 1 octave
+pitch_with_octave = note.pitch      # => 76
 
 # Chromatic operations - sharp and flat
 c_sharp = c_major.tonic.sharp   # => C# (chromatic, +1 semitone)
@@ -93,6 +137,49 @@ third_up = c_major.tonic.sharp(4)  # => E (+4 semitones = major third)
 # Frequency calculation
 frequency = c_major.tonic.frequency  # => 261.63 Hz (middle C at A=440)
 
+# Greek modes (church modes)
+d_dorian = tuning.dorian[62]         # D Dorian (minor with major 6th)
+e_phrygian = tuning.phrygian[64]     # E Phrygian (minor with minor 2nd)
+f_lydian = tuning.lydian[65]         # F Lydian (major with augmented 4th)
+g_mixolydian = tuning.mixolydian[67] # G Mixolydian (major with minor 7th)
+b_locrian = tuning.locrian[71]       # B Locrian (diminished 5th)
+
+# Access notes in Greek modes by function
+d_dorian.tonic.pitch      # => 62 (D)
+d_dorian[:vi].pitch       # => 71 (B - the major 6th characteristic of Dorian)
+
+e_phrygian[:ii].pitch     # => 65 (F - the minor 2nd characteristic of Phrygian)
+
+f_lydian[:IV].pitch       # => 71 (B - the augmented 4th characteristic of Lydian)
+
+g_mixolydian[:VII].pitch  # => 77 (F - the minor 7th characteristic of Mixolydian)
+
+b_locrian[:v].pitch       # => 77 (F - the diminished 5th characteristic of Locrian)
+
+# Pentatonic and blues scales
+c_pent_maj = tuning.pentatonic_major[60]  # C major pentatonic
+a_pent_min = tuning.pentatonic_minor[69]  # A minor pentatonic
+a_blues = tuning.blues[69]                 # A blues scale
+a_blues[:blue].pitch  # => 75 (Eb - the blue note)
+
+# Symmetric scales
+c_whole = tuning.whole_tone[60]      # C whole tone
+c_dim_hw = tuning.diminished_hw[60]  # C diminished (half-whole)
+c_dim_wh = tuning.diminished_wh[60]  # C diminished (whole-half)
+
+# Melodic minor modes
+c_mel_min = tuning.minor_melodic[60]     # C melodic minor
+g_altered = tuning.altered[67]            # G altered (for G7alt chords)
+f_lyd_dom = tuning.lydian_dominant[65]   # F lydian dominant (F7#11)
+
+# Ethnic scales
+e_phry_dom = tuning.phrygian_dominant[64]  # E Phrygian dominant (flamenco)
+a_hung_min = tuning.hungarian_minor[69]    # A Hungarian minor
+
+# Bebop scales (8 notes for smooth eighth-note lines)
+g_bebop = tuning.bebop_dominant[67]  # G bebop dominant
+g_bebop[7].pitch  # => 78 (F# - the chromatic passing tone)
+
 # Create chords from scale degrees
 i_chord = c_major.tonic.chord        # C major triad [C, E, G]
 ii_chord = c_major.supertonic.chord  # D minor triad [D, F, A]
@@ -124,15 +211,258 @@ seventh_chord = i_chord.with_size(:seventh)  # C major 7th
 ninth_chord = i_chord.with_size(:ninth)      # C major 9th
 
 # Voicing modifications - move specific tones to different octaves
-voiced = i_chord.move(root: -1, fifth: 1)  # Root down, fifth up
+voiced = i_chord.with_move(root: -1, fifth: 1)  # Root down, fifth up
+i_chord.move  # => { root: -1, fifth: 1 } (current settings)
 
 # Duplicate tones in other octaves
-doubled = i_chord.duplicate(root: -2, third: [-1, 1])  # Root 2 down, third 1 down and 1 up
+doubled = i_chord.with_duplicate(root: -2, third: [-1, 1])  # Root 2 down, third 1 down and 1 up
+i_chord.duplicate  # => { root: -2, third: [-1, 1] } (current settings)
 
 # Transpose entire chord
 lower = i_chord.octave(-1)  # Move chord down one octave
 ```
 
+### Chord-Scale Navigation
+
+MusaDSL provides methods to explore the relationship between chords and scales,
+enabling harmonic analysis and discovery of functional contexts.
+
+#### Checking if a Scale Contains a Chord
+
+```ruby
+c_major = Scales.et12[440.0].major[60]
+g7 = c_major.dominant.chord :seventh
+
+c_major.contains_chord?(g7)     # => true
+c_major.degree_of_chord(g7)     # => 4 (V degree, 0-based)
+
+# Non-diatonic chords return false/nil
+cm = c_major.tonic.chord.with_quality(:minor)  # C minor (Eb not in C major)
+c_major.contains_chord?(cm)     # => false
+c_major.degree_of_chord(cm)     # => nil
+```
+
+#### Creating a Chord in a Different Scale Context
+
+```ruby
+# Get the same chord but with a different scale as context
+g_mixolydian = Scales.et12[440.0].mixolydian[67]
+g7_in_mixolydian = g7.as_chord_in_scale(g_mixolydian)
+g7_in_mixolydian.scale                        # => G Mixolydian scale
+g_mixolydian.degree_of_chord(g7_in_mixolydian)  # => 0 (I degree)
+```
+
+#### Creating Chords from Scale Degrees
+
+```ruby
+# Create chords directly from scale degrees using Scale#chord_on
+i_chord = scale.chord_on(0)                    # Tonic triad
+v7 = scale.chord_on(:dominant, :seventh)       # V7
+iv_maj7 = scale.chord_on(:IV, :seventh, :major)  # IVmaj7
+
+# Equivalent to using the note method then chord:
+scale[0].chord                      # Same as scale.chord_on(0)
+scale[:dominant].chord(:seventh)    # Same as scale.chord_on(:dominant, :seventh)
+
+# With voicing parameters
+scale.chord_on(:I, :seventh, move: {root: -1})
+scale.chord_on(0, :triad, duplicate: {root: 1})
+```
+
+#### Finding Scales That Contain a Chord
+
+```ruby
+g_triad = c_major.dominant.chord  # G-B-D
+
+# Search in diatonic scales
+g_triad.search_in_scales(family: :diatonic)
+# => [Chord in C major (V), Chord in G major (I), Chord in D major (IV), ...]
+
+# Search using metadata filters
+g_triad.search_in_scales(family: :greek_modes, brightness: -1..1)
+
+# Search in all scale types
+g_triad.search_in_scales
+
+# Each result has its scale context
+g_triad.search_in_scales(family: :diatonic).each do |chord|
+  scale = chord.scale
+  degree = scale.degree_of_chord(chord)
+  puts "#{scale.kind.class.id} rooted on #{scale.root_pitch}: degree #{degree}"
+end
+# Output:
+# major rooted on 60: degree 4
+# major rooted on 67: degree 0
+# major rooted on 62: degree 3
+```
+
+#### Low-Level Navigation Methods
+
+```ruby
+tuning = Scales.et12[440.0]
+
+# Search at ScaleKind level
+tuning.major.find_chord_in_scales(g_triad)
+
+# Search at ScaleSystemTuning level with metadata filters
+tuning.search_chord_in_scales(g7, family: :diatonic, roots: 60..71)
+```
+
+### Scale Kind Metadata
+
+Scale kinds in MusaDSL have a three-layer metadata system that provides
+both automatic structural information and extensible custom properties.
+
+#### Metadata Layers
+
+1. **Intrinsic metadata**: Automatically derived from scale structure
+   - `id`: Scale kind identifier
+   - `grades`: Number of scale degrees
+   - `pitches`: Array of pitch offsets from root
+   - `intervals`: Intervals between consecutive degrees
+   - `has_leading_tone`: Whether scale has pitch 11 (semitone below octave)
+   - `has_tritone`: Whether scale contains tritone interval (pitch 6)
+   - `symmetric`: Type of symmetry if any (`:equal`, `:palindrome`, `:repeating`)
+
+2. **Base metadata**: Defined by musa-dsl library
+   - `family`: Scale family (`:diatonic`, `:greek_modes`, `:pentatonic`, etc.)
+   - `brightness`: Relative brightness (-3 to +3, major = 0)
+   - `character`: Array of descriptive tags
+   - `parent`: Parent scale and degree for modes (e.g., `{ scale: :major, degree: 2 }`)
+
+3. **Custom metadata**: Added by users at runtime
+
+#### Accessing Metadata
+
+```ruby
+tuning = Scales.et12[440.0]
+major_class = tuning.major.class
+
+# Get combined metadata (intrinsic < base < custom)
+major_class.metadata
+# => { id: :major, grades: 7, pitches: [0,2,4,5,7,9,11], family: :diatonic, ... }
+
+# Get specific layer
+major_class.intrinsic_metadata  # Structure-derived only
+major_class.base_metadata       # Library-defined only
+major_class.custom_metadata     # User-added only
+
+# Query helpers
+major_class.has_metadata?(:family)              # => true
+major_class.has_metadata?(:family, :diatonic)   # => true
+major_class.has_metadata?(:character, :bright)  # => true (array inclusion)
+major_class.metadata_value(:brightness)         # => 0
+```
+
+#### Extending Metadata
+
+Users can add custom metadata to any scale kind:
+
+```ruby
+# Extend a specific scale kind class
+tuning.dorian.class.extend_metadata(
+  my_mood: :nostalgic,
+  suitable_for: [:jazz, :fusion],
+  personal_rating: 5
+)
+
+# Or use the convenience method with scale ID
+Scales.extend_metadata(:dorian, my_mood: :nostalgic)
+
+# Multiple calls merge metadata
+Scales.extend_metadata(:phrygian, mood: :dark)
+Scales.extend_metadata(:phrygian, origin: :spanish)  # Merges with previous
+
+# Reset custom metadata if needed
+tuning.dorian.class.reset_custom_metadata
+```
+
+#### Custom Metadata Overrides
+
+Custom metadata takes precedence over base metadata:
+
+```ruby
+# Override library-defined family
+Scales.extend_metadata(:dorian, family: :my_custom_category)
+tuning.dorian.class.metadata[:family]  # => :my_custom_category
+```
+
+#### Brightness Scale Reference
+
+| Value | Meaning | Examples |
+|-------|---------|----------|
+| +3 | Very bright | Lydian augmented |
+| +2 | Bright | Lydian |
+| +1 | Slightly bright | Mixolydian, Lydian dominant |
+| 0 | Neutral (reference) | Major (Ionian) |
+| -1 | Slightly dark | Dorian |
+| -2 | Dark | Minor harmonic, Phrygian |
+| -3 | Very dark | Locrian, Natural minor |
+
+#### Scale Families
+
+- `:diatonic` - Major, minor natural, minor harmonic
+- `:greek_modes` - Dorian, Phrygian, Lydian, Mixolydian, Locrian
+- `:melodic_minor_modes` - Melodic minor and its modes
+- `:pentatonic` - Pentatonic major/minor
+- `:blues` - Blues scales
+- `:bebop` - Bebop scales
+- `:symmetric` - Whole tone, diminished
+- `:ethnic` - Hungarian, Spanish, Neapolitan, etc.
+- `:chromatic` - Chromatic scale
+
+### Searching Scale Kinds
+
+The `scale_kinds` method on ScaleSystemTuning allows searching and filtering
+scale kinds by their metadata properties.
+
+#### Basic Usage
+
+```ruby
+tuning = Scales.et12[440.0]
+
+# Get all scale kinds
+tuning.scale_kinds
+# => [major_kind, minor_kind, dorian_kind, ...]
+
+# Filter by family
+tuning.scale_kinds(family: :diatonic)
+# => [major_kind, minor_kind, minor_harmonic_kind, harmonic_major_kind]
+
+# Filter by brightness range
+tuning.scale_kinds(brightness: -1..1)
+
+# Filter by character
+tuning.scale_kinds(character: :jazz)
+```
+
+#### Custom Filtering with Blocks
+
+Use a block for complex filtering based on any metadata:
+
+```ruby
+# Scales with leading tone
+tuning.scale_kinds { |klass| klass.intrinsic_metadata[:has_leading_tone] }
+
+# Combine criteria and block
+tuning.scale_kinds(family: :greek_modes) { |klass| klass.metadata[:brightness]&.negative? }
+# => [dorian_kind, phrygian_kind, locrian_kind]
+```
+
+#### Integration with Chord Search
+
+The `search_chord_in_scales` method uses the same metadata filtering:
+
+```ruby
+g7 = tuning.major[60].dominant.chord(:seventh)
+
+# Find G7 in diatonic scales
+tuning.search_chord_in_scales(g7, family: :diatonic)
+
+# Find G7 in scales with specific brightness
+tuning.search_chord_in_scales(g7, brightness: -1..1)
+```
+
 ## Defining Custom Scale Systems, Scale Kinds, and Chord Definitions
 
 The framework is extensible, allowing users to define custom tuning systems, scale types, and chord structures:
@@ -173,19 +503,19 @@ require 'musa-dsl'
 include Musa::Scales
 include Musa::Chords
 
-# Example 1: Define a custom pentatonic scale kind for the 12-tone system
-class PentatonicMajorScaleKind < ScaleKind
+# Example 1: Define a custom Hirajoshi scale (Japanese pentatonic)
+class HirajoshiScaleKind < ScaleKind
   class << self
     def id
-      :pentatonic_major
+      :hirajoshi
     end
 
     def pitches
       [{ functions: [:I, :_1, :tonic], pitch: 0 },
        { functions: [:II, :_2], pitch: 2 },
-       { functions: [:III, :_3], pitch: 4 },
-       { functions: [:V, :_5], pitch: 7 },
-       { functions: [:VI, :_6], pitch: 9 }]
+       { functions: [:III, :_3], pitch: 3 },
+       { functions: [:V, :_4], pitch: 7 },
+       { functions: [:VI, :_5], pitch: 8 }]
     end
 
     def grades
@@ -195,14 +525,14 @@ class PentatonicMajorScaleKind < ScaleKind
 end
 
 # Register the new scale kind with the 12-tone system
-Scales.et12.register(PentatonicMajorScaleKind)
+Scales.et12.register(HirajoshiScaleKind)
 
 # Use the new scale kind
 tuning = Scales.default_system.default_tuning
-c_pentatonic = tuning[:pentatonic_major][60]  # C pentatonic major
-puts c_pentatonic[0].pitch  # => 60 (C)
-puts c_pentatonic[1].pitch  # => 62 (D)
-puts c_pentatonic[2].pitch  # => 64 (E)
+c_hirajoshi = tuning[:hirajoshi][60]  # C Hirajoshi
+puts c_hirajoshi[0].pitch  # => 60 (C)
+puts c_hirajoshi[1].pitch  # => 62 (D)
+puts c_hirajoshi[2].pitch  # => 63 (Eb)
 
 # Example 2: Register a custom chord definition (sus4)
 Musa::Chords::ChordDefinition.register :sus4,

data/docs/subsystems/transport.md

@@ -87,6 +87,32 @@ dummy_clock = Musa::Clock::DummyClock.new(100)
 4. **on_change_position** - Run when position jumps/seeks
 5. **after_stop** - Run when transport stops
 
+### Clean Shutdown
+
+To cleanly terminate a transport using TimerClock:
+
+1. Call `transport.stop` from within a scheduled event
+2. This calls `clock.terminate` internally
+3. The clock's run loop exits
+4. `transport.start` returns
+5. Your code continues after `transport.start` for cleanup
+
+```ruby
+# Example: Self-terminating composition
+transport.sequencer.at 10 do
+  puts "Composition finished"
+  transport.stop  # This will cause transport.start to return
+end
+
+transport.start  # Blocks until transport.stop is called
+puts "Cleanup..."  # Executes after stop
+output.close
+```
+
+**Note:** For `InputMidiClock`, stop/start cycles are controlled by the DAW
+and don't terminate the process. The `terminate` method can be used explicitly
+if you need the run loop to exit.
+
 **Key methods:**
 - `start` - Start playback (blocks while running)
 - `stop` - Stop playback

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Musical dataset framework for MusaDSL.
 #
 # The Datasets module provides a comprehensive framework for representing and transforming

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

@@ -204,7 +204,7 @@ module Musa::Datasets
         pdv[:pitch] = if self[:silence]
                         :silence
                       else
-                        scale[self[:grade]].sharp(self[:sharps] || 0).octave(self[:octave] || 0).pitch
+                        scale[self[:grade]].sharp(self[:sharps] || 0).at_octave(self[:octave] || 0).pitch
                       end
       end
 
@@ -399,8 +399,8 @@ module Musa::Datasets
             (self[:sharps] || 0) != (previous[:sharps] || 0)
 
             gdvd[:delta_grade] =
-                scale[self[:grade]].octave(self[:octave]).wide_grade -
-                scale[previous[:grade]].octave(previous[:octave]).wide_grade
+                scale[self[:grade]].at_octave(self[:octave]).wide_grade -
+                scale[previous[:grade]].at_octave(previous[:octave]).wide_grade
 
             gdvd[:delta_sharps] = (self[:sharps] || 0) - (previous[:sharps] || 0)
           end

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

@@ -206,7 +206,7 @@ module Musa::Datasets
     #
     # @api private
     class PtoTimedSerie
-      include Musa::Series::Serie.base
+      include Musa::Series::Serie::Base
 
       # Creates new timed serie adapter.
       #

data/lib/musa-dsl/datasets/score/to-mxml/process-time.rb

@@ -42,7 +42,8 @@ module Musa::Datasets::Score::ToMXML
     # @note This method is experimental and currently unused. See TODO comment.
     #
     # @api private
-    def initialize(element, bar, bar_size = 1r) # TODO remove (unused because of bad strategy to time groups)
+    def initialize(element, bar, bar_size = Rational(1))
+      # TODO remove (unused because of bad strategy to time groups)
       @continue_from_previous_bar = element[:start] < bar
       @continue_to_next_bar = element[:finish] >= bar + bar_size
 
@@ -99,7 +100,8 @@ module Musa::Datasets::Score::ToMXML
   #
   # @api private
   # @todo Complete or remove this experimental method
-  def time_and_tuplet_optimize(elements, bar, bar_size = 1r) # TODO remove (unused because of bad strategy to time groups)
+  def time_and_tuplet_optimize(elements, bar, bar_size = Rational(1))
+    # TODO remove (unused because of bad strategy to time groups)
     decompositions = elements.collect { |pdv| ElementDurationDecomposition.new(pdv, bar, bar_size) }
 
     denominators = decompositions.collect { |g| g.duration_decomposition.collect { |d| d.to_r.denominator } }.flatten.uniq

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

@@ -143,12 +143,14 @@ module Musa::Datasets
     # @return [Object, nil] attribute value
     #
     # @api private
-    def [](key)
+    def get(key)
       if NaturalKeys.include?(key) && self.respond_to?(key)
         self.send(key)
       end
     end
 
+    alias_method :[], :get
+
     # Returns latest finish time of all events.
     #
     # @return [Rational, nil] latest finish time, or nil if score is empty

data/lib/musa-dsl/generative/darwin.rb

@@ -104,6 +104,8 @@ module Musa
       #     measures { |obj| dimension :value, obj[:score] }
       #     weight value: 1.0
       #   end
+      #
+      # @return [void]
       def initialize(&block)
         raise ArgumentError, 'block is needed' unless block
 
@@ -175,6 +177,14 @@ module Musa
         measured_objects.collect { |measured_object| measured_object[:object] }
       end
 
+      # Compares two measures by their weighted fitness.
+      #
+      # @param measure_a [Measure] first measure to compare
+      # @param measure_b [Measure] second measure to compare
+      #
+      # @return [Integer] comparison result (-1, 0, 1)
+      #
+      # @api private
       def evaluate_weights(measure_a, measure_b)
         measure_b.evaluate_weight(@weights) <=> measure_a.evaluate_weight(@weights)
       end
@@ -189,6 +199,7 @@ module Musa
         # @return [Hash] weight assignments
         attr_reader :_measures, :_weights
 
+        # @return [void]
         # @api private
         def initialize(&block)
           @_weights = {}
@@ -198,6 +209,9 @@ module Musa
         # Defines measures evaluation block.
         #
         # @yield [object] measures DSL block
+        #
+        # @return [Proc] the measures block
+        #
         # @api private
         def measures(&block)
           @_measures = block
@@ -205,7 +219,10 @@ module Musa
 
         # Assigns weights to features/dimensions.
         #
-        # @param feature_or_dimension_weights [Hash] name => weight pairs
+        # @param feature_or_dimension_weights [Hash{Symbol => Numeric}] name => weight pairs
+        #
+        # @return [void]
+        #
         # @api private
         def weight(**feature_or_dimension_weights)
           feature_or_dimension_weights.each do |name, value|
@@ -220,6 +237,7 @@ module Musa
       class MeasuresEvalContext
         include Musa::Extension::With
 
+        # @return [void]
         # @api private
         def initialize
           @_features = {}
@@ -238,6 +256,9 @@ module Musa
         # Marks object as having a feature.
         #
         # @param feature_name [Symbol] feature identifier
+        #
+        # @return [void]
+        #
         # @api private
         def feature(feature_name)
           @_features[feature_name] = true
@@ -247,6 +268,9 @@ module Musa
         #
         # @param dimension_name [Symbol] dimension identifier
         # @param value [Numeric] measured value
+        #
+        # @return [void]
+        #
         # @api private
         def dimension(dimension_name, value)
           @_dimensions[dimension_name] = value
@@ -254,6 +278,8 @@ module Musa
 
         # Marks object as non-viable (to be excluded).
         #
+        # @return [void]
+        #
         # @api private
         def die
           @_died = true
@@ -280,6 +306,12 @@ module Musa
       class Measure
         attr_reader :features, :dimensions, :normalized_dimensions
 
+        # @param features [Hash{Symbol => Boolean}] feature flags
+        # @param dimensions [Hash{Symbol => Numeric}] dimension values
+        # @param died [Boolean] viability status
+        #
+        # @return [void]
+        #
         # @api private
         def initialize(features, dimensions, died)
           @features = features
@@ -319,6 +351,9 @@ module Musa
           total
         end
 
+        # Returns string representation of measure.
+        #
+        # @return [String] formatted measure description
         def inspect
           "Measure features=#{@features.collect { |k, _v| k }} dimensions=#{@normalized_dimensions.collect { |k, v| [k, [@dimensions[k].round(5), v.round(2)]] }.to_h}"
         end