musa-dsl 0.30.2 → 0.40.0

data/lib/musa-dsl/musicxml/builder/helper.rb

@@ -1,17 +1,162 @@
 module Musa
+  # MusicXML generation system.
+  #
+  # This module provides a comprehensive DSL for generating MusicXML 3.0 files
+  # programmatically. It uses a builder pattern with a flexible API that supports
+  # both constructor-based and DSL-style notation creation.
+  #
+  # ## Architecture
+  #
+  # The MusicXML builder system is organized hierarchically:
+  #
+  #     ScorePartwise (root)
+  #       ├── Metadata (work, movement, creators, rights)
+  #       ├── PartGroup (grouping)
+  #       └── Part
+  #           └── Measure
+  #               ├── Attributes (key, time, clef, divisions)
+  #               ├── Direction (dynamics, tempo, expressions)
+  #               ├── PitchedNote / Rest / UnpitchedNote
+  #               └── Backup / Forward (timeline navigation)
+  #
+  # ## DSL Features
+  #
+  # The builder provides two equivalent ways to create scores:
+  #
+  # 1. **Constructor + add methods**: Imperative style
+  # 2. **DSL blocks**: Declarative style with `with` blocks
+  #
+  # Both styles leverage `AttributeBuilder` and `With` mixins from core-ext.
+  #
+  # ## Use Cases
+  #
+  # - Algorithmic composition with MusicXML export
+  # - Score generation from Musa DSL performances
+  # - Converting MIDI recordings to notation
+  # - Creating notation examples programmatically
+  #
+  # @example Simple score with DSL style
+  #   score = Musa::MusicXML::Builder::ScorePartwise.new do
+  #     work_title "My Composition"
+  #     creators composer: "Composer Name"
+  #
+  #     part :p1, name: "Piano" do
+  #       measure do
+  #         attributes do
+  #           divisions 2
+  #           key fifths: 0  # C major
+  #           time beats: 4, beat_type: 4
+  #           clef sign: 'G', line: 2
+  #         end
+  #
+  #         pitch 'C', octave: 4, duration: 2, type: 'quarter'
+  #         pitch 'D', octave: 4, duration: 2, type: 'quarter'
+  #         pitch 'E', octave: 4, duration: 2, type: 'quarter'
+  #         pitch 'F', octave: 4, duration: 2, type: 'quarter'
+  #       end
+  #     end
+  #   end
+  #
+  #   File.write('output.xml', score.to_xml.string)
+  #
+  # @example Constructor + add methods style
+  #   score = Musa::MusicXML::Builder::ScorePartwise.new
+  #   score.work_title = "My Composition"
+  #   score.add_creator "composer", "Composer Name"
+  #
+  #   part = score.add_part :p1, name: "Piano"
+  #   measure = part.add_measure divisions: 2
+  #   measure.attributes.last.add_key fifths: 0
+  #   measure.attributes.last.add_time beats: 4, beat_type: 4
+  #   measure.attributes.last.add_clef sign: 'G', line: 2
+  #
+  #   measure.add_pitch step: 'C', octave: 4, duration: 2, type: 'quarter'
+  #
+  #   File.write('output.xml', score.to_xml.string)
+  #
+  # @see Builder Main builder namespace
+  # @see Builder::ScorePartwise Entry point for score creation
   module MusicXML
+    # Builder classes for MusicXML generation.
+    #
+    # Contains all the builder classes that construct MusicXML elements.
+    # The main entry point is {ScorePartwise}.
+    #
+    # @see ScorePartwise Main score builder
     module Builder
+      # Internal implementation classes for MusicXML builder.
+      #
+      # This module contains the actual implementation classes used by the builder.
+      # Users should access these through the main `Musa::MusicXML::Builder` namespace.
+      #
+      # @api private
       module Internal
+        # Helper modules and methods for MusicXML generation.
+        #
+        # Provides shared functionality for XML serialization, element construction,
+        # and value formatting across all builder classes.
         module Helper
+          # Mixin for classes not yet implemented.
+          #
+          # Used as a placeholder for MusicXML elements that are planned but not
+          # yet implemented. Raises `NotImplementedError` when attempting to use.
+          #
+          # @api private
           module NotImplemented
+            # Placeholder initializer accepting any parameters.
+            #
+            # @param _args [Hash] ignored keyword arguments
             def initialize(**_args); end
 
+            # Raises error indicating the class is not implemented.
+            #
+            # @param io [IO, nil] ignored
+            # @param indent [Integer, nil] ignored
+            # @raise [NotImplementedError] always raised with helpful message
             def to_xml(io = nil, indent: nil)
               raise NotImplementedError, "#{self.class} not yet implemented. Ask Javier do his work!"
             end
           end
 
+          # Mixin for XML serialization capability.
+          #
+          # Provides the public `to_xml` interface that handles IO and indentation
+          # setup, delegating to the private `_to_xml` method for actual XML generation.
+          #
+          # ## Usage
+          #
+          # Classes including this module must implement `_to_xml(io, indent:, tabs:)`.
+          #
+          # @example Including in a class
+          #   class MyElement
+          #     include Musa::MusicXML::Builder::Internal::Helper::ToXML
+          #
+          #     private
+          #
+          #     def _to_xml(io, indent:, tabs:)
+          #       io.puts "#{tabs}<my-element />"
+          #     end
+          #   end
+          #
+          #   element = MyElement.new
+          #   element.to_xml  # => StringIO with XML content
           module ToXML
+            # Converts the object to MusicXML format.
+            #
+            # This method sets up the IO stream and indentation, then delegates to
+            # the private `_to_xml` method for actual XML generation.
+            #
+            # @param io [IO, StringIO, nil] output stream (creates StringIO if nil)
+            # @param indent [Integer, nil] indentation level (default: 0)
+            # @return [IO, StringIO] the io parameter, containing the XML output
+            #
+            # @example Writing to file
+            #   File.open('output.xml', 'w') do |f|
+            #     element.to_xml(f)
+            #   end
+            #
+            # @example Getting XML as string
+            #   xml_string = element.to_xml.string
             def to_xml(io = nil, indent: nil)
               io ||= StringIO.new
               indent ||= 0
@@ -25,10 +170,34 @@ module Musa
 
             private
 
+            # Abstract method for XML generation.
+            #
+            # Subclasses must implement this method to generate their XML content.
+            #
+            # @param io [IO] output stream to write XML to
+            # @param indent [Integer] current indentation level
+            # @param tabs [String] precomputed tab string for current indent
+            # @return [void]
+            #
+            # @api private
             def _to_xml(io, indent:, tabs:); end
           end
 
+          # Mixin for XML header serialization (used in part-list).
+          #
+          # Similar to {ToXML}, but for elements that appear in the `<part-list>`
+          # section of MusicXML (parts and part groups).
+          #
+          # Classes including this module must implement `_header_to_xml(io, indent:, tabs:)`.
           module HeaderToXML
+            # Converts the object's header representation to MusicXML.
+            #
+            # Used for elements that appear in the `<part-list>` section, such as
+            # `<score-part>` and `<part-group>` declarations.
+            #
+            # @param io [IO, StringIO, nil] output stream (creates StringIO if nil)
+            # @param indent [Integer, nil] indentation level (default: 0)
+            # @return [IO, StringIO] the io parameter, containing the XML output
             def header_to_xml(io = nil, indent: nil)
               io ||= StringIO.new
               indent ||= 0
@@ -42,11 +211,40 @@ module Musa
 
             private
 
+            # Abstract method for header XML generation.
+            #
+            # Subclasses must implement this method to generate their header XML.
+            #
+            # @param io [IO] output stream to write XML to
+            # @param indent [Integer] current indentation level
+            # @param tabs [String] precomputed tab string for current indent
+            # @return [void]
+            #
+            # @api private
             def _header_to_xml(io, indent:, tabs:); end
           end
 
           private
 
+          # Creates class instance from Hash or returns existing instance.
+          #
+          # This helper method provides flexible parameter handling, allowing
+          # methods to accept either a fully-constructed instance or a hash of
+          # constructor parameters.
+          #
+          # @param klass [Class] expected class type
+          # @param hash_or_class_instance [klass, Hash, nil] value to process
+          # @return [klass, nil] instance of klass, or nil
+          #
+          # @raise [ArgumentError] if value is not klass, Hash, or nil
+          #
+          # @example Flexible parameter acceptance
+          #   # Method can accept either:
+          #   time_modification: { actual_notes: 3, normal_notes: 2 }
+          #   # or:
+          #   time_modification: TimeModification.new(actual_notes: 3, normal_notes: 2)
+          #
+          # @api private
           def make_instance_if_needed(klass, hash_or_class_instance)
             case hash_or_class_instance
             when klass
@@ -60,6 +258,33 @@ module Musa
             end
           end
 
+          # Converts value to XML attribute string with boolean support.
+          #
+          # Handles three types of values:
+          # - **String/Numeric**: Outputs as attribute value
+          # - **true**: Outputs specified true_value (if provided)
+          # - **false**: Outputs specified false_value (if provided)
+          # - **Other**: Returns empty string (omits attribute)
+          #
+          # @param value [Object] value to convert
+          # @param attribute [String] attribute name
+          # @param true_value [String, nil] value to use for `true`
+          # @param false_value [String, nil] value to use for `false`
+          # @return [String] formatted attribute string or empty string
+          #
+          # @example String value
+          #   decode_bool_or_string_attribute('above', 'placement')
+          #   # => ' placement="above"'
+          #
+          # @example Boolean with mappings
+          #   decode_bool_or_string_attribute(true, 'bracket', 'yes', 'no')
+          #   # => ' bracket="yes"'
+          #
+          # @example Nil value
+          #   decode_bool_or_string_attribute(nil, 'placement')
+          #   # => ''
+          #
+          # @api private
           def decode_bool_or_string_attribute(value, attribute, true_value = nil, false_value = nil)
             if value.is_a?(String) || value.is_a?(Numeric)
               " #{attribute}=\"#{value}\""
@@ -72,6 +297,21 @@ module Musa
             end
           end
 
+          # Converts value to XML element content with boolean support.
+          #
+          # Similar to {#decode_bool_or_string_attribute} but for element content
+          # rather than attributes.
+          #
+          # @param value [Object] value to convert
+          # @param true_value [String, nil] value to use for `true`
+          # @param false_value [String, nil] value to use for `false`
+          # @return [String] formatted content string or empty string
+          #
+          # @example
+          #   decode_bool_or_string_value(true, 'yes', 'no')  # => 'yes'
+          #   decode_bool_or_string_value('dashed')          # => 'dashed'
+          #
+          # @api private
           def decode_bool_or_string_value(value, true_value = nil, false_value = nil)
             if value.is_a?(String) || value.is_a?(Numeric)
               value

data/lib/musa-dsl/musicxml/builder/measure.rb

@@ -13,12 +13,117 @@ module Musa
   module MusicXML
     module Builder
       module Internal
+        # Measure container for musical content.
+        #
+        # Measure represents a single measure (bar) of music, containing musical elements
+        # in chronological order: attributes, notes, rests, backup/forward commands, and
+        # directions (dynamics, tempo markings, etc.).
+        #
+        # ## Element Order
+        #
+        # Elements within a measure follow MusicXML's sequential model:
+        # 1. **Attributes** (key, time, clef, divisions) - typically in first measure
+        # 2. **Directions** (tempo, dynamics) - before or between notes
+        # 3. **Notes/Rests** - musical content
+        # 4. **Backup/Forward** - timeline navigation for multiple voices/staves
+        #
+        # ## Multiple Voices and Staves
+        #
+        # For piano (grand staff) or polyphonic notation, use backup to rewind the timeline:
+        #
+        #     measure do
+        #       # Right hand (treble clef)
+        #       pitch 'C', octave: 5, duration: 4, type: 'quarter', staff: 1
+        #       pitch 'D', octave: 5, duration: 4, type: 'quarter', staff: 1
+        #
+        #       backup 8  # Rewind to start of measure
+        #
+        #       # Left hand (bass clef)
+        #       pitch 'C', octave: 3, duration: 8, type: 'half', staff: 2
+        #     end
+        #
+        # ## Divisions
+        #
+        # The `divisions` attribute sets timing resolution (divisions per quarter note).
+        # Higher values allow finer rhythmic subdivisions:
+        # - **divisions: 1** → quarter, half, whole only
+        # - **divisions: 2** → adds eighths
+        # - **divisions: 4** → adds sixteenths
+        # - **divisions: 8** → adds thirty-seconds
+        # - **divisions: 16** → allows complex tuplets
+        #
+        # Duration is calculated as: `duration = (note_type_value * divisions) / beat_type`
+        #
+        # @example Simple measure with quarter notes
+        #   measure = Measure.new(1, divisions: 2) do
+        #     attributes do
+        #       key fifths: 0  # C major
+        #       time beats: 4, beat_type: 4
+        #       clef sign: 'G', line: 2
+        #     end
+        #
+        #     pitch 'C', octave: 4, duration: 2, type: 'quarter'
+        #     pitch 'D', octave: 4, duration: 2, type: 'quarter'
+        #     pitch 'E', octave: 4, duration: 2, type: 'quarter'
+        #     pitch 'F', octave: 4, duration: 2, type: 'quarter'
+        #   end
+        #
+        # @example Measure with dynamics and tempo
+        #   measure do
+        #     metronome beat_unit: 'quarter', per_minute: 120
+        #
+        #     direction do
+        #       dynamics 'p'
+        #       wedge 'crescendo'
+        #     end
+        #
+        #     pitch 'C', octave: 4, duration: 4, type: 'quarter'
+        #     pitch 'D', octave: 4, duration: 4, type: 'quarter'
+        #
+        #     direction do
+        #       wedge 'stop'
+        #       dynamics 'f'
+        #     end
+        #   end
+        #
+        # @see Attributes Musical attributes (key, time, clef)
+        # @see PitchedNote Pitched note
+        # @see Rest Rest
+        # @see Direction Tempo, dynamics, expressions
         class Measure
           extend Musa::Extension::AttributeBuilder
           include Musa::Extension::With
 
           include Helper::ToXML
 
+          # Creates a new measure.
+          #
+          # @param number [Integer] measure number (automatically assigned by Part)
+          # @param divisions [Integer, nil] divisions per quarter note (timing resolution)
+          # @param key_cancel [Integer, nil] key cancellation
+          # @param key_fifths [Integer, nil] key signature (-7 to +7, circle of fifths)
+          # @param key_mode [String, nil] mode ('major' or 'minor')
+          # @param time_senza_misura [Boolean, nil] unmeasured time
+          # @param time_beats [Integer, nil] time signature numerator
+          # @param time_beat_type [Integer, nil] time signature denominator
+          # @param clef_sign [String, nil] clef sign ('G', 'F', 'C')
+          # @param clef_line [Integer, nil] clef line number
+          # @param clef_octave_change [Integer, nil] octave transposition
+          # @yield Optional DSL block for adding measure content
+          #
+          # @example First measure with all attributes
+          #   Measure.new(1,
+          #     divisions: 4,
+          #     key_fifths: 2,  # D major
+          #     time_beats: 3, time_beat_type: 4,
+          #     clef_sign: 'G', clef_line: 2
+          #   )
+          #
+          # @example Measure with DSL block
+          #   Measure.new(2) do
+          #     pitch 'E', octave: 4, duration: 4, type: 'quarter'
+          #     rest duration: 4, type: 'quarter'
+          #   end
           def initialize(number, divisions: nil,
                          key_cancel: nil, key_fifths: nil, key_mode: nil,
                          time_senza_misura: nil, time_beats: nil, time_beat_type: nil,
@@ -44,9 +149,39 @@ module Musa
             with &block if block_given?
           end
 
+          # Measure number.
+          # @return [Integer]
           attr_accessor :number
+
+          # Ordered list of elements in this measure.
+          # @return [Array<Object>] notes, rests, attributes, directions, etc.
           attr_reader :elements
 
+          # Adds musical attributes to the measure.
+          #
+          # Attributes define key signature, time signature, clef, and timing divisions.
+          # Typically appear at the start of the first measure or when they change.
+          #
+          # @option divisions [Integer, nil] divisions per quarter note
+          # @option key_cancel [Integer, nil] key to cancel
+          # @option key_fifths [Integer, nil] key signature (-7 to +7)
+          # @option key_mode [String, nil] 'major' or 'minor'
+          # @option time_senza_misura [Boolean, nil] unmeasured time
+          # @option time_beats [Integer, nil] time signature numerator
+          # @option time_beat_type [Integer, nil] time signature denominator
+          # @option clef_sign [String, nil] 'G', 'F', or 'C'
+          # @option clef_line [Integer, nil] clef line
+          # @option clef_octave_change [Integer, nil] octave transposition
+          # @yield Optional DSL block for adding keys, times, clefs
+          # @return [Attributes] the created attributes object
+          #
+          # @example Via DSL block
+          #   measure.attributes do
+          #     divisions 4
+          #     key fifths: 1  # G major
+          #     time beats: 3, beat_type: 4
+          #     clef sign: 'G', line: 2
+          #   end
           attr_complex_adder_to_custom :attributes, plural: :attributes, variable: :@attributes do
           | divisions: nil,
               key_cancel: nil, key_fifths: nil, key_mode: nil,
@@ -65,62 +200,211 @@ module Musa
             end
           end
 
+          # Adds a pitched note.
+          #
+          # @return [PitchedNote] the created note
+          #
+          # @example
+          #   measure.pitch 'C', octave: 4, duration: 4, type: 'quarter'
+          #   measure.pitch step: 'E', octave: 4, duration: 2, type: 'eighth', dots: 1
+          #
+          # @see PitchedNote For full parameter list
           attr_complex_adder_to_custom :pitch do | *parameters, **key_parameters |
             PitchedNote.new(*parameters, **key_parameters).tap { |note| @elements << note }
           end
 
+          # Adds a rest.
+          #
+          # @return [Rest] the created rest
+          #
+          # @example
+          #   measure.rest duration: 4, type: 'quarter'
+          #   measure.rest duration: 8, type: 'half', measure: true  # whole measure rest
+          #
+          # @see Rest For full parameter list
           attr_complex_adder_to_custom :rest do | *parameters, **key_parameters |
             Rest.new(*parameters, **key_parameters).tap { |rest| @elements << rest }
           end
 
+          # Adds an unpitched note (for percussion).
+          #
+          # @return [UnpitchedNote] the created unpitched note
+          #
+          # @see UnpitchedNote For details
           attr_complex_adder_to_custom :unpitched do | *parameters, **key_parameters |
             UnpitchedNote.new(*parameters, **key_parameters).tap { |unpitched| @elements << unpitched }
           end
 
+          # Rewinds the musical timeline.
+          #
+          # Backup moves the current time position backward by the specified duration,
+          # allowing multiple voices or staves to be layered in the same time span.
+          #
+          # @return [Backup] the created backup element
+          #
+          # @example Piano grand staff
+          #   measure do
+          #     pitch 'C', octave: 5, duration: 8, type: 'half', staff: 1
+          #     backup 8  # Rewind to start
+          #     pitch 'C', octave: 3, duration: 8, type: 'half', staff: 2
+          #   end
+          #
+          # @see Forward For moving forward
           attr_complex_adder_to_custom :backup do |duration|
             Backup.new(duration).tap { |backup| @elements << backup }
           end
 
+          # Advances the musical timeline.
+          #
+          # Forward moves the current time position forward without sounding,
+          # creating rests or gaps in the timeline.
+          #
+          # @return [Forward] the created forward element
+          #
+          # @example Skip to beat 3
+          #   measure do
+          #     pitch 'C', octave: 4, duration: 2, type: 'quarter'
+          #     forward 4  # Skip 2 beats
+          #     pitch 'D', octave: 4, duration: 2, type: 'quarter'
+          #   end
           attr_complex_adder_to_custom :forward do |duration, voice: nil, staff: nil|
             Forward.new(duration, voice: voice, staff: staff).tap { |forward| @elements << forward }
           end
 
+          # Adds a direction element (dynamics, tempo, expressions).
+          #
+          # Directions contain non-note musical instructions like dynamics (p, f),
+          # tempo markings, wedges (crescendo/diminuendo), pedal marks, etc.
+          #
+          # @yield Optional DSL block for direction content
+          # @return [Direction] the created direction
+          #
+          # @example Dynamics with crescendo
+          #   measure.direction do
+          #     dynamics 'p'
+          #     wedge 'crescendo'
+          #   end
+          #
+          # @see Direction For direction types
           attr_complex_adder_to_custom :direction do |*parameters, **key_parameters, &block|
             Direction.new(*parameters, **key_parameters, &block).tap { |direction| @elements << direction }
           end
 
+          # Direction shortcuts - these create a Direction automatically.
+          #
+          # The following methods are convenience shortcuts that create a Direction
+          # element containing the specified direction type. They accept placement and
+          # offset parameters that are passed to the Direction wrapper.
+
+          # Adds a metronome (tempo) marking.
+          #
+          # @option placement [String, nil] 'above' or 'below'
+          # @option offset [Numeric, nil] offset in divisions
+          # @option beat_unit [String] note value ('quarter', 'half', etc.)
+          # @option per_minute [Numeric] tempo in BPM
+          # @yield Optional block
+          # @return [Direction] direction containing metronome
+          #
+          # @example
+          #   measure.metronome beat_unit: 'quarter', per_minute: 120
           attr_complex_adder_to_custom(:metronome) {
             |*p, placement: nil, offset: nil, **kp, &b|
             direction(placement: placement, offset: offset) { metronome *p, **kp, &b } }
 
+          # Adds a wedge (crescendo/diminuendo).
+          #
+          # @option placement [String, nil] 'above' or 'below'
+          # @option offset [Numeric, nil] offset in divisions
+          # @option niente [Boolean, nil] niente attribute
+          # @return [Direction] direction containing wedge
+          #
+          # @example
+          #   measure.wedge 'crescendo', niente: true
           attr_complex_adder_to_custom(:wedge) {
             |*p, placement: nil, offset: nil, **kp, &b|
             direction(placement: placement, offset: offset) { wedge *p, **kp, &b } }
 
+          # Adds dynamics (p, pp, f, ff, etc.).
+          #
+          # @option placement [String, nil] 'above' or 'below'
+          # @option offset [Numeric, nil] offset in divisions
+          # @return [Direction] direction containing dynamics
+          #
+          # @example
+          #   measure.dynamics 'pp'
+          #   measure.dynamics ['mf', 'sf']  # Multiple dynamics
           attr_complex_adder_to_custom(:dynamics) {
             |*p, placement: nil, offset: nil, **kp, &b|
             direction(placement: placement, offset: offset) { dynamics *p, **kp, &b } }
 
+          # Adds pedal marking.
+          #
+          # @option placement [String, nil] 'above' or 'below'
+          # @option offset [Numeric, nil] offset in divisions
+          # @option line [Boolean, nil] show pedal line
+          # @return [Direction] direction containing pedal
+          #
+          # @example
+          #   measure.pedal 'start', line: true
           attr_complex_adder_to_custom(:pedal) {
             |*p, placement: nil, offset: nil, **kp, &b|
             direction(placement: placement, offset: offset) { pedal *p, **kp, &b } }
 
+          # Adds bracket notation.
+          #
+          # @option placement [String, nil] 'above' or 'below'
+          # @option offset [Numeric, nil] offset in divisions
+          # @option line_end [String, nil] line end type
+          # @return [Direction] direction containing bracket
           attr_complex_adder_to_custom(:bracket) {
             |*p, placement: nil, offset: nil, **kp, &b|
             direction(placement: placement, offset: offset) { bracket *p, **kp, &b } }
 
+          # Adds dashed line.
+          #
+          # @option placement [String, nil] 'above' or 'below'
+          # @option offset [Numeric, nil] offset in divisions
+          # @return [Direction] direction containing dashes
           attr_complex_adder_to_custom(:dashes) {
             |*p, placement: nil, offset: nil, **kp, &b|
             direction(placement: placement, offset: offset) { dashes *p, **kp, &b } }
 
+          # Adds text annotation.
+          #
+          # @option placement [String, nil] 'above' or 'below'
+          # @option offset [Numeric, nil] offset in divisions
+          # @return [Direction] direction containing words
+          #
+          # @example
+          #   measure.words "rit.", placement: 'above'
           attr_complex_adder_to_custom(:words) {
             |*p, placement: nil, offset: nil, **kp, &b|
             direction(placement: placement, offset: offset) { words *p, **kp, &b } }
 
+          # Adds octave shift (8va/8vb).
+          #
+          # @option placement [String, nil] 'above' or 'below'
+          # @option offset [Numeric, nil] offset in divisions
+          # @option size [Integer, nil] octave shift size (8 or 15)
+          # @return [Direction] direction containing octave_shift
+          #
+          # @example
+          #   measure.octave_shift 'up', size: 8
           attr_complex_adder_to_custom(:octave_shift) {
             |*p, placement: nil, offset: nil, **kp, &b|
             direction(placement: placement, offset: offset) { octave_shift *p, **kp, &b } }
 
+          # Generates the measure XML element with all contained elements.
+          #
+          # Outputs elements in the order they were added, which must follow
+          # MusicXML's element ordering rules (attributes, then notes/directions/backup/forward).
+          #
+          # @param io [IO] output stream
+          # @param indent [Integer] indentation level
+          # @param tabs [String] tab string
+          # @return [void]
+          #
+          # @api private
           def _to_xml(io, indent:, tabs:)
             io.puts "#{tabs}<measure number=\"#{@number.to_i}\">"