musa-dsl 0.30.2 → 0.40.0

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

@@ -7,9 +7,26 @@ module Musa
   module MusicXML
     module Builder
       module Internal
+        # Notation element helper.
+        #
+        # Private helper class for creating MusicXML notation elements with
+        # type attributes and optional content. Used internally for elements
+        # like slurs, which can be simple (type: 'start'/'stop') or complex
+        # (with additional attributes like placement, bezier curves, etc.).
+        #
+        # @api private
         class Notation
           include Helper::ToXML
 
+          # Creates a Notation from various input formats.
+          #
+          # @param tag [String] XML element tag name
+          # @param value_or_attributes [Symbol, String, Hash, nil] type value or hash of attributes
+          # @param true_value [String, nil] value to use when type is true
+          # @param false_value [String, nil] value to use when type is false
+          # @return [Notation, nil]
+          #
+          # @api private
           def self.create(tag, value_or_attributes, true_value = nil, false_value = nil)
             case value_or_attributes
             when Hash
@@ -28,6 +45,16 @@ module Musa
             end
           end
 
+          # Creates a notation element.
+          #
+          # @param tag [String] XML element tag name
+          # @param type [Symbol, String, Boolean] type attribute value
+          # @param content [String, nil] element text content
+          # @param true_value [String, nil] value to use when type is true
+          # @param false_value [String, nil] value to use when type is false
+          # @param attributes [Hash] additional XML attributes
+          #
+          # @api private
           def initialize(tag, type, content = nil, true_value = nil, false_value = nil, **attributes)
             @tag = tag
 
@@ -43,6 +70,14 @@ module Musa
             @attributes = attributes
           end
 
+          # Generates the notation XML element.
+          #
+          # @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.print "#{tabs}\t<#{ @tag } "
 
@@ -62,6 +97,108 @@ module Musa
 
         private_constant :Notation
 
+        # Abstract base class for all note types.
+        #
+        # Note is the foundation for pitched notes, rests, and unpitched percussion notes.
+        # It provides comprehensive support for musical notation including:
+        #
+        # ## Core Note Properties
+        # - **Duration and Type**: Timing (duration in divisions, type: whole/half/quarter/etc.)
+        # - **Voice and Staff**: Multi-voice and multi-staff support
+        # - **Dots**: Dotted and double-dotted notes
+        # - **Grace Notes**: Ornamental notes without duration
+        # - **Cue Notes**: Smaller notes for reference
+        # - **Chords**: Notes that sound simultaneously
+        #
+        # ## Notations
+        # The `<notations>` element groups musical symbols attached to notes:
+        #
+        # ### Basic Notations
+        # - **Ties/Tied**: Visual ties connecting notes (tie) vs sustained sound (tied)
+        # - **Slurs**: Phrase markings
+        # - **Tuplets**: Irregular rhythmic groupings (triplets, quintuplets, etc.)
+        # - **Dynamics**: Volume markings (pp, p, mp, mf, f, ff, etc.)
+        # - **Fermata**: Pause/hold symbols
+        # - **Accidental Marks**: Sharp, flat, natural annotations
+        # - **Arpeggiate**: Rolled chord indication
+        # - **Glissando/Slide**: Pitch glide
+        #
+        # ### Articulations
+        # Attack and release characteristics:
+        # - **accent**: Emphasis (>)
+        # - **staccato**: Short, detached (•)
+        # - **tenuto**: Full value (−)
+        # - **staccatissimo**: Very short (▼)
+        # - **spiccato**: Bouncing bow
+        # - **strong_accent**: Forceful (^)
+        # - **detached_legato**: Portato
+        # - **breath_mark**: Breath pause
+        # - **caesura**: Railroad tracks (caesura)
+        # - Plus: doit, falloff, plop, scoop, stress, unstress
+        #
+        # ### Ornaments
+        # Melodic decorations:
+        # - **trill_mark**: Rapid alternation with upper neighbor
+        # - **mordent**: Single alternation with lower neighbor
+        # - **inverted_mordent**: Single alternation with upper neighbor
+        # - **turn**: Four-note figure around main note
+        # - **inverted_turn**: Inverted turn figure
+        # - **delayed_turn**: Turn after main note
+        # - **shake**: Extended trill
+        # - **tremolo**: Rapid repetition (single) or alternation (start/stop)
+        # - **schleifer**: Slide ornament
+        # - **wavy_line**: Trill extension
+        #
+        # ### Technical Markings
+        # Performance technique indicators:
+        #
+        # **String Instruments**:
+        # - **fingering**: Finger numbers
+        # - **up_bow/down_bow**: Bowing direction (↑/↓)
+        # - **harmonic**: Natural or artificial harmonics
+        # - **open_string**: Open string indication (○)
+        # - **stopped**: Stopped note (+)
+        # - **snap_pizzicato**: Bartók pizzicato
+        # - **thumb_position**: Cello thumb position
+        # - **string**: String number
+        # - **hammer_on/pull_off**: Legato technique
+        #
+        # **Wind Instruments**:
+        # - **double_tongue/triple_tongue**: Tonguing technique
+        # - **fingernails**: Use fingernails
+        # - **hole**: Woodwind fingering holes
+        #
+        # **Guitar/Fretted**:
+        # - **fret**: Fret number
+        # - **bend**: String bend
+        # - **tap**: Tapping technique
+        # - **pluck**: Plucking style
+        #
+        # **Other**:
+        # - **arrow**: Directional arrow
+        # - **handbell**: Handbell technique (damp, echo, gyro, etc.)
+        # - **heel/toe**: Organ pedal technique
+        #
+        # ## Hierarchy
+        #
+        # Note is an abstract base class with three concrete subclasses:
+        # - {PitchedNote}: Notes with specific pitch (step, octave, alteration)
+        # - {Rest}: Silences with duration
+        # - {UnpitchedNote}: Percussion notes without specific pitch
+        #
+        # ## Usage
+        #
+        # Note is not used directly—use {PitchedNote}, {Rest}, or {UnpitchedNote}.
+        # Notes are typically added via {Measure} convenience methods:
+        # - {Measure#add_pitch} / {Measure#pitch}
+        # - {Measure#add_rest} / {Measure#rest}
+        # - {Measure#add_unpitched} / {Measure#unpitched}
+        #
+        # @abstract Subclass and override {#specific_to_xml} to implement.
+        # @see PitchedNote Pitched notes with step/octave
+        # @see Rest Rests and measure rests
+        # @see UnpitchedNote Unpitched percussion
+        # @see Measure Container for notes
         class Note
           extend Musa::Extension::AttributeBuilder
           include Musa::Extension::With
@@ -69,6 +206,127 @@ module Musa
           include Helper
           include ToXML
 
+          # Creates a note (abstract base constructor).
+          #
+          # This constructor is called by subclasses ({PitchedNote}, {Rest}, {UnpitchedNote}).
+          # The extensive parameter list supports all MusicXML notation features.
+          #
+          # ## Parameter Categories
+          #
+          # ### Core Note Properties
+          # @param grace [Boolean, nil] grace note (ornamental, no time value)
+          # @param cue [Boolean, nil] cue note (smaller, reference indication)
+          # @param chord [Boolean, nil] note is part of a chord (sounds with previous note)
+          # @param duration [Integer, nil] duration in division units
+          # @param type [String, nil] note type: 'whole', 'half', 'quarter', 'eighth', '16th', etc.
+          # @param dots [Integer, nil] number of augmentation dots (1 or 2)
+          # @param voice [Integer, nil] voice number for polyphonic music
+          # @param staff [Integer, nil] staff number for multi-staff instruments
+          # @param tie_start [Boolean, nil] start a tie to next note
+          # @param tie_stop [Boolean, nil] stop a tie from previous note
+          # @param accidental [String, nil] visual accidental: 'sharp', 'flat', 'natural', etc.
+          # @param stem [String, nil] stem direction: 'up', 'down', 'double', 'none'
+          # @param pizzicato [Boolean, nil] pizzicato attribute on note element
+          #
+          # ### Rhythm Modification
+          # @param time_modification [TimeModification, Hash, nil] tuplet ratio (e.g., 3:2 for triplets)
+          # @param notehead [Notehead, Hash, nil] notehead style and properties
+          #
+          # ### Basic Notations
+          # @param tied [String, nil] tied notation: 'start', 'stop', 'continue'
+          # @param tuplet [Tuplet, Hash, nil] tuplet bracket/number notation
+          # @param slur [String, Hash, nil] slur: 'start', 'stop', 'continue' or hash with attributes
+          # @param dynamics [String, Array<String>, nil] dynamics: 'pp', 'p', 'mp', 'mf', 'f', 'ff', etc.
+          # @param fermata [Boolean, String, nil] fermata: true, 'upright', 'inverted'
+          # @param accidental_mark [String, nil] accidental in notations: 'sharp', 'flat', 'natural'
+          # @param arpeggiate [Boolean, String, nil] arpeggio: true, 'up', 'down'
+          # @param non_arpeggiate [String, nil] non-arpeggio: 'top', 'bottom'
+          # @param glissando [String, nil] glissando: 'start', 'stop'
+          # @param slide [String, nil] slide: 'start', 'stop'
+          #
+          # ### Articulations
+          # @param accent [Boolean, nil] accent mark (>)
+          # @param staccato [Boolean, nil] staccato (•)
+          # @param tenuto [Boolean, nil] tenuto (−)
+          # @param staccatissimo [Boolean, nil] staccatissimo (▼)
+          # @param spiccato [Boolean, nil] spiccato
+          # @param strong_accent [Boolean, String, nil] strong accent (^): true, 'up', 'down'
+          # @param detached_legato [Boolean, nil] detached legato (portato)
+          # @param breath_mark [Boolean, String, nil] breath mark: true, 'comma', 'tick'
+          # @param caesura [Boolean, nil] caesura (railroad tracks)
+          # @param doit [Boolean, nil] doit
+          # @param falloff [Boolean, nil] falloff
+          # @param plop [Boolean, nil] plop
+          # @param scoop [Boolean, nil] scoop
+          # @param stress [Boolean, nil] stress
+          # @param unstress [Boolean, nil] unstress
+          # @param other_articulation [String, nil] custom articulation text
+          #
+          # ### Ornaments
+          # @param trill_mark [Boolean, nil] trill
+          # @param mordent [Boolean, nil] mordent (lower neighbor)
+          # @param inverted_mordent [Boolean, nil] inverted mordent (upper neighbor)
+          # @param turn [Boolean, nil] turn
+          # @param inverted_turn [Boolean, nil] inverted turn
+          # @param delayed_turn [Boolean, nil] delayed turn
+          # @param delayed_inverted_turn [Boolean, nil] delayed inverted turn
+          # @param shake [Boolean, nil] shake
+          # @param tremolo [String, nil] tremolo: 'single', 'start', 'stop'
+          # @param schleifer [Boolean, nil] schleifer
+          # @param wavy_line [Boolean, nil] wavy line (trill extension)
+          # @param vertical_turn [Boolean, nil] vertical turn
+          # @param other_ornament [Boolean, nil] custom ornament
+          # @param ornament_accidental_mark [String, nil] ornament accidental: 'sharp', 'flat', 'natural'
+          #
+          # ### String Technique
+          # @param fingering [Fingering, Hash, nil] fingering indication
+          # @param up_bow [Boolean, nil] up bow (↑)
+          # @param down_bow [Boolean, nil] down bow (↓)
+          # @param harmonic [Harmonic, Hash, nil] harmonic
+          # @param open_string [Boolean, nil] open string (○)
+          # @param stopped [Boolean, nil] stopped note (+)
+          # @param snap_pizzicato [Boolean, nil] Bartók pizzicato
+          # @param thumb_position [Boolean, nil] cello thumb position
+          # @param string [Integer, nil] string number
+          # @param hammer_on [String, nil] hammer-on: 'start', 'stop'
+          # @param pull_off [String, nil] pull-off: 'start', 'stop'
+          #
+          # ### Wind Technique
+          # @param double_tongue [Boolean, nil] double tonguing
+          # @param triple_tongue [Boolean, nil] triple tonguing
+          # @param fingernails [Boolean, nil] use fingernails
+          # @param hole [Hole, Hash, nil] woodwind fingering hole
+          #
+          # ### Fretted Instrument Technique
+          # @param fret [Integer, nil] fret number
+          # @param bend [Bend, Hash, nil] string bend
+          # @param tap [String, nil] tapping
+          # @param pluck [String, nil] plucking technique
+          #
+          # ### Other Technical
+          # @param arrow [Arrow, Hash, nil] arrow indication
+          # @param handbell [String, nil] handbell technique: 'damp', 'echo', 'gyro', etc.
+          # @param heel [Boolean, nil] heel (organ pedal)
+          # @param toe [Boolean, nil] toe (organ pedal)
+          # @param other_technical [String, nil] custom technical text
+          #
+          # @yield Optional DSL block for setting properties
+          #
+          # @example Basic quarter note with staccato
+          #   PitchedNote.new('C', octave: 4, duration: 2, type: 'quarter', staccato: true)
+          #
+          # @example Dotted eighth with slur start
+          #   PitchedNote.new('D', octave: 5, duration: 3, type: 'eighth', dots: 1, slur: 'start')
+          #
+          # @example Grace note with accent
+          #   PitchedNote.new('E', octave: 5, grace: true, type: 'eighth', accent: true)
+          #
+          # @example Multi-voice with fermata
+          #   PitchedNote.new('G', octave: 4, duration: 4, type: 'half', voice: 2, fermata: true)
+          #
+          # For detailed parameter documentation, see {NoteComplexities::PARAMETERS}
+          #
+          # @api private (called by subclasses)
           def initialize(*_rest,
                          pizzicato: nil,  # true
                          # main content
@@ -351,6 +609,18 @@ module Musa
           attr_simple_builder :triple_tongue
           attr_simple_builder :up_bow
 
+          # Generates the note XML element.
+          #
+          # Outputs a complete `<note>` element with all sub-elements in MusicXML order:
+          # grace, cue, chord, pitch/rest/unpitched, duration, tie, voice, type, dots,
+          # accidental, time_modification, stem, notehead, staff, notations.
+          #
+          # @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}<note#{" pizzicato=\"yes\"" if @pizzicato}>"
 
@@ -488,8 +758,23 @@ module Musa
 
           private
 
+          # Outputs note-type-specific XML content.
+          #
+          # Abstract method overridden by subclasses to output pitch, rest, or unpitched elements.
+          # Called during XML generation between chord and duration elements.
+          #
+          # @param io [IO] output stream
+          # @param indent [Integer] indentation level
+          # @return [void]
+          #
+          # @abstract Subclasses must implement this method
+          # @api private
           def specific_to_xml(io, indent:); end
 
+          # Checks if any notation elements are present.
+          #
+          # @return [Boolean] true if any notations should be output
+          # @api private
           def _notations
             @accidental_mark ||
                 @arpeggiate ||

data/lib/musa-dsl/musicxml/builder/part-group.rb

@@ -4,10 +4,83 @@ module Musa
   module MusicXML
     module Builder
       module Internal
+        # Part group for bracketing multiple parts together.
+        #
+        # PartGroup represents the `<part-group>` element in the MusicXML part-list
+        # section. Part groups visually bracket or brace related parts together
+        # (e.g., string sections, choir SATB, piano grand staff).
+        #
+        # ## Usage
+        #
+        # Part groups are defined by matching start/stop pairs with the same number:
+        #
+        #     <part-group number="1" type="start">
+        #       <group-name>Strings</group-name>
+        #       <group-symbol>bracket</group-symbol>
+        #     </part-group>
+        #     <score-part id="p1">...</score-part>
+        #     <score-part id="p2">...</score-part>
+        #     <part-group number="1" type="stop" />
+        #
+        # ## Nesting
+        #
+        # Groups can be nested using different numbers:
+        #
+        #     <part-group number="1" type="start" name="Orchestra" />
+        #     <part-group number="2" type="start" name="Strings" />
+        #     <score-part id="vln1" />
+        #     <score-part id="vln2" />
+        #     <part-group number="2" type="stop" />
+        #     <part-group number="1" type="stop" />
+        #
+        # ## Symbols
+        #
+        # Common bracket symbols:
+        # - **bracket**: Standard square bracket
+        # - **brace**: Curly brace (for piano, organ)
+        # - **line**: Simple vertical line
+        # - **square**: Square bracket (rare)
+        #
+        # @example String quartet grouping
+        #   group_start = PartGroup.new(1,
+        #     type: 'start',
+        #     name: "String Quartet",
+        #     symbol: 'bracket'
+        #   )
+        #   # ... add parts vln1, vln2, vla, vlc ...
+        #   group_stop = PartGroup.new(1, type: 'stop')
+        #
+        # @example Piano grand staff
+        #   PartGroup.new(1,
+        #     type: 'start',
+        #     symbol: 'brace',
+        #     group_barline: true
+        #   )
+        #   # ... add parts for right hand and left hand ...
+        #   PartGroup.new(1, type: 'stop')
         class PartGroup
           include Helper
           include Helper::HeaderToXML
 
+          # Creates a part group declaration.
+          #
+          # @param number [Integer, nil] group number for matching start/stop pairs
+          # @param type [String] 'start' or 'stop'
+          # @param name [String, nil] group name displayed on bracket
+          # @param abbreviation [String, nil] abbreviated group name
+          # @param symbol [String, nil] bracket type: 'bracket', 'brace', 'line', 'square'
+          # @param group_barline [Boolean, String, nil] whether barlines connect across group
+          # @param group_time [Boolean, String, nil] whether time signatures are shared
+          #
+          # @example Start a bracket group
+          #   PartGroup.new(1,
+          #     type: 'start',
+          #     name: "Woodwinds",
+          #     symbol: 'bracket'
+          #   )
+          #
+          # @example Stop a group
+          #   PartGroup.new(1, type: 'stop')
           def initialize(number = nil, # number
                          type:,
                          name: nil,
@@ -24,8 +97,42 @@ module Musa
             @group_time = group_time
           end
 
-          attr_accessor :number, :type, :name, :abbreviation, :symbol, :group_barline, :group_time
+          # Group number (for matching start/stop pairs).
+          # @return [Integer, nil]
+          attr_accessor :number
 
+          # Type: 'start' or 'stop'.
+          # @return [String]
+          attr_accessor :type
+
+          # Group name displayed on bracket.
+          # @return [String, nil]
+          attr_accessor :name
+
+          # Abbreviated group name.
+          # @return [String, nil]
+          attr_accessor :abbreviation
+
+          # Bracket symbol type.
+          # @return [String, nil]
+          attr_accessor :symbol
+
+          # Whether barlines connect across the group.
+          # @return [Boolean, String, nil]
+          attr_accessor :group_barline
+
+          # Whether time signatures are shared.
+          # @return [Boolean, String, nil]
+          attr_accessor :group_time
+
+          # Generates the part-group XML element for the part-list section.
+          #
+          # @param io [IO] output stream
+          # @param indent [Integer] indentation level
+          # @param tabs [String] tab string
+          # @return [void]
+          #
+          # @api private
           def _header_to_xml(io, indent:, tabs:)
             io.puts "#{tabs}<part-group#{ decode_bool_or_string_attribute(@number&.to_i, 'number') } type=\"#{@type}\">"
 

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

@@ -8,6 +8,43 @@ module Musa
   module MusicXML
     module Builder
       module Internal
+        # Individual part (instrument/voice) in a score.
+        #
+        # Part represents a single instrument or voice in the score, containing
+        # a sequence of measures with musical content. Each part has a unique
+        # identifier, full name, and optional abbreviation.
+        #
+        # ## Structure
+        #
+        # A part contains:
+        # - **Header**: Declared in `<part-list>` with `<score-part>`
+        # - **Content**: Sequence of `<measure>` elements with notes, dynamics, etc.
+        #
+        # ## Usage
+        #
+        # Parts are typically created via {Musa::MusicXML::Builder::ScorePartwise#part} or {Musa::MusicXML::Builder::ScorePartwise#add_part}.
+        # Measures are added sequentially, automatically numbered starting from 1.
+        #
+        # @example Creating a part with measures
+        #   part = Part.new(:p1, name: "Violin I", abbreviation: "Vln. I") do
+        #     measure do
+        #       attributes do
+        #         divisions 4
+        #         key fifths: 1  # G major
+        #         time beats: 4, beat_type: 4
+        #         clef sign: 'G', line: 2
+        #       end
+        #       pitch 'D', octave: 5, duration: 4, type: 'quarter'
+        #     end
+        #
+        #     measure do
+        #       pitch 'E', octave: 5, duration: 4, type: 'quarter'
+        #       pitch 'F', octave: 5, duration: 4, type: 'quarter', alter: 1
+        #     end
+        #   end
+        #
+        # @see Measure Measure implementation
+        # @see ScorePartwise#part Main way to create parts
         class Part
           extend Musa::Extension::AttributeBuilder
           include Musa::Extension::With
@@ -15,6 +52,31 @@ module Musa
           include Helper::HeaderToXML
           include Helper::ToXML
 
+          # Creates a new part.
+          #
+          # @param id [Symbol, String] unique part identifier (referenced in `<part>` elements)
+          # @param name [String] full part name (e.g., "Violin I", "Piano")
+          # @param abbreviation [String, nil] abbreviated name for subsequent systems
+          # @param first_measure_attributes [Hash] optional attributes for auto-created first measure
+          # @yield Optional DSL block for adding measures
+          #
+          # @example With abbreviation
+          #   Part.new(:p1, name: "Violoncello", abbreviation: "Vc.")
+          #
+          # @example With first measure attributes
+          #   Part.new(:p1,
+          #     name: "Flute",
+          #     divisions: 4,
+          #     key_fifths: 0,
+          #     time_beats: 3, time_beat_type: 4
+          #   )
+          #
+          # @example With DSL block
+          #   Part.new(:p1, name: "Clarinet") do
+          #     measure do
+          #       # measure content
+          #     end
+          #   end
           def initialize(id, name:, abbreviation: nil, **first_measure_attributes, &block)
             @id = id
             @name = name
@@ -29,10 +91,67 @@ module Musa
             with &block if block_given?
           end
 
+          # Part ID builder/setter.
+          #
+          # @overload id(value)
+          #   Sets part ID via DSL
+          #   @param value [Symbol, String] part identifier
+          # @overload id=(value)
+          #   Sets part ID via assignment
+          #   @param value [Symbol, String] part identifier
           attr_simple_builder :id
+
+          # Part name builder/setter.
+          #
+          # @overload name(value)
+          #   Sets part name via DSL
+          #   @param value [String] part name
+          # @overload name=(value)
+          #   Sets part name via assignment
+          #   @param value [String] part name
           attr_simple_builder :name
+
+          # Part abbreviation builder/setter.
+          #
+          # @overload abbreviation(value)
+          #   Sets abbreviation via DSL
+          #   @param value [String] abbreviated name
+          # @overload abbreviation=(value)
+          #   Sets abbreviation via assignment
+          #   @param value [String] abbreviated name
           attr_simple_builder :abbreviation
 
+          # Adds a measure to the part.
+          #
+          # Measures are automatically numbered sequentially starting from 1.
+          # The first measure typically contains attributes (key, time, clef, divisions).
+          #
+          # @option divisions [Integer, nil] divisions per quarter note (timing resolution)
+          # @option key_cancel [Integer, nil] key cancellation
+          # @option key_fifths [Integer, nil] key signature (circle of fifths: -7 to +7)
+          # @option key_mode [String, nil] mode (major/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] clef sign (G/F/C)
+          # @option clef_line [Integer, nil] clef line number
+          # @option clef_octave_change [Integer, nil] octave transposition
+          # @yield Optional DSL block for measure content
+          # @return [Measure] the created measure
+          #
+          # @example First measure with attributes
+          #   part.add_measure(
+          #     divisions: 4,
+          #     key_fifths: 2,  # D major
+          #     time_beats: 4, time_beat_type: 4,
+          #     clef_sign: 'G', clef_line: 2
+          #   )
+          #
+          # @example Measure with DSL block
+          #   part.measure do
+          #     pitch 'C', octave: 4, duration: 4, type: 'quarter'
+          #     rest duration: 4, type: 'quarter'
+          #   end
           attr_complex_adder_to_custom :measure, variable: :@measures do
           | divisions: nil,
               key_cancel: nil, key_fifths: nil, key_mode: nil,
@@ -46,6 +165,16 @@ module Musa
                         clef_sign: clef_sign, clef_line: clef_line, clef_octave_change: clef_octave_change).tap { |measure| @measures << measure }
           end
 
+          # Generates the part declaration for the part-list section.
+          #
+          # Creates a `<score-part>` element with part name and optional abbreviation.
+          #
+          # @param io [IO] output stream
+          # @param indent [Integer] indentation level
+          # @param tabs [String] tab string
+          # @return [void]
+          #
+          # @api private
           def _header_to_xml(io, indent:, tabs:)
             io.puts "#{tabs}<score-part id=\"#{@id}\">"
             io.puts "#{tabs}\t<part-name>#{@name}</part-name>"
@@ -53,6 +182,16 @@ module Musa
             io.puts "#{tabs}</score-part>"
           end
 
+          # Generates the part content with all measures.
+          #
+          # Creates a `<part>` element containing all measures in sequence.
+          #
+          # @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}<part id=\"#{@id}\">"
             @measures.each do |measure|