musa-dsl 0.30.2 → 0.40.0

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

@@ -4,7 +4,83 @@ module Musa
   module MusicXML
     module Builder
       module Internal
+        # Unpitched note for percussion and rhythm-only notation.
+        #
+        # UnpitchedNote represents notes without specific pitch, primarily used
+        # for percussion instruments in drum notation. It extends {Note} with
+        # simplified pitch handling—no step, alter, or octave needed.
+        #
+        # ## Use Cases
+        #
+        # ### Percussion Notation
+        # Drum kits, percussion ensembles, and rhythm sections use unpitched notes
+        # where vertical position on the staff indicates the instrument (not pitch):
+        #
+        # - Snare drum
+        # - Bass drum
+        # - Hi-hat
+        # - Cymbals
+        # - Toms
+        # - Auxiliary percussion
+        #
+        # ### Rhythm-Only Notation
+        # Teaching materials and rhythm exercises where pitch is irrelevant.
+        #
+        # ### Tablature
+        # Some tablature systems use unpitched notes with fret/string indications.
+        #
+        # ## Staff Position
+        #
+        # Unlike pitched notes, staff line position doesn't represent pitch but rather
+        # identifies the percussion instrument. This mapping is defined by the clef
+        # (typically percussion clef) and is instrument-specific.
+        #
+        # ## Combining with Technical Markings
+        #
+        # Unpitched notes support all standard notations (dynamics, articulations, etc.)
+        # but often use percussion-specific technicals like sticking patterns.
+        #
+        # ## Usage
+        #
+        # Created via Measure#add_unpitched or Measure#unpitched:
+        #
+        #     measure.unpitched duration: 2, type: 'quarter'
+        #     measure.add_unpitched duration: 1, type: 'eighth', accent: true
+        #
+        # @example Basic unpitched quarter note
+        #   UnpitchedNote.new(duration: 2, type: 'quarter')
+        #
+        # @example Snare drum hit with accent
+        #   UnpitchedNote.new(duration: 2, type: 'quarter', accent: true)
+        #
+        # @example Hi-hat with staccato
+        #   UnpitchedNote.new(duration: 1, type: 'eighth', staccato: true)
+        #
+        # @example Bass drum with forte dynamic
+        #   UnpitchedNote.new(duration: 4, type: 'half', dynamics: 'f')
+        #
+        # @example Cymbal crash with fermata
+        #   UnpitchedNote.new(duration: 8, type: 'whole', fermata: true)
+        #
+        # @see Note Base class with all notation attributes
+        # @see PitchedNote Pitched notes
+        # @see Rest Rests
+        # @see Measure Container for adding notes
         class UnpitchedNote < Note
+          # Creates an unpitched note.
+          #
+          # @param (see Note#initialize) All Note parameters are supported
+          #
+          # @example Percussion quarter note
+          #   UnpitchedNote.new(duration: 2, type: 'quarter')
+          #
+          # @example Eighth note with accent
+          #   UnpitchedNote.new(duration: 1, type: 'eighth', accent: true)
+          #
+          # @example Dotted half with forte
+          #   UnpitchedNote.new(duration: 6, type: 'half', dots: 1, dynamics: 'f')
+          #
+          # For detailed parameter documentation, see {Note#initialize}
           def initialize( pizzicato: nil, # true
                           grace: nil, # true
                           cue: nil, # true
@@ -101,6 +177,13 @@ module Musa
 
           private
 
+          # Outputs the unpitched XML element.
+          #
+          # @param io [IO] output stream
+          # @param indent [Integer] indentation level
+          # @return [void]
+          #
+          # @api private
           def specific_to_xml(io, indent:)
             tabs = "\t" * indent
             io.puts "#{tabs}<unpitched />"