musa-dsl 0.30.2 → 0.40.0

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

@@ -4,7 +4,101 @@ module Musa
   module MusicXML
     module Builder
       module Internal
+        # Pitched note with specific step, octave, and optional alteration.
+        #
+        # PitchedNote represents notes with defined pitches (as opposed to rests or
+        # unpitched percussion). It extends {Note} with pitch information: step (C-G),
+        # octave (scientific pitch notation), and optional chromatic alteration.
+        #
+        # ## Pitch Components
+        #
+        # ### Step
+        # The diatonic pitch class: 'C', 'D', 'E', 'F', 'G', 'A', 'B'
+        #
+        # ### Octave
+        # Scientific pitch notation (middle C = C4):
+        # - Octave 0: C0 to B0 (subcontra octave)
+        # - Octave 4: C4 to B4 (one-line octave, middle C)
+        # - Octave 8: C8 to B8 (five-line octave)
+        #
+        # ### Alter
+        # Chromatic alteration in semitones:
+        # - **-2**: Double flat
+        # - **-1**: Flat
+        # - **0**: Natural (can be omitted)
+        # - **+1**: Sharp
+        # - **+2**: Double sharp
+        #
+        # ## Accidentals
+        #
+        # The `alter` parameter changes the sounding pitch, while the `accidental`
+        # parameter controls visual display:
+        #
+        # - **alter**: Affects playback (actual pitch)
+        # - **accidental**: Visual symbol (sharp, flat, natural, etc.)
+        #
+        # Usually both are specified together, but you can have:
+        # - alter without accidental (implied by key signature)
+        # - accidental without alter (cautionary accidental)
+        #
+        # ## Usage
+        #
+        # Created via Measure#add_pitch or Measure#pitch:
+        #
+        #     measure.pitch 'C', octave: 5, duration: 4, type: 'quarter'
+        #     measure.add_pitch step: 'F', alter: 1, octave: 4, duration: 2, type: 'eighth'
+        #
+        # @example Middle C quarter note
+        #   PitchedNote.new('C', octave: 4, duration: 4, type: 'quarter')
+        #
+        # @example F# with sharp symbol
+        #   PitchedNote.new('F', alter: 1, octave: 5, duration: 2, type: 'eighth',
+        #                   accidental: 'sharp')
+        #
+        # @example Bb dotted half note with staccato
+        #   PitchedNote.new('B', alter: -1, octave: 4, duration: 6, type: 'half',
+        #                   dots: 1, accidental: 'flat', staccato: true)
+        #
+        # @example High A with trill
+        #   PitchedNote.new('A', octave: 6, duration: 8, type: 'whole',
+        #                   trill_mark: true)
+        #
+        # @example Chord notes (C major triad)
+        #   measure.pitch 'C', octave: 4, duration: 4, type: 'quarter'
+        #   measure.pitch 'E', octave: 4, duration: 4, type: 'quarter', chord: true
+        #   measure.pitch 'G', octave: 4, duration: 4, type: 'quarter', chord: true
+        #
+        # @example Grace note with slur
+        #   PitchedNote.new('D', octave: 5, grace: true, type: 'eighth',
+        #                   slur: 'start')
+        #
+        # @see Note Base class with all notation attributes
+        # @see Rest Rest notes
+        # @see UnpitchedNote Unpitched percussion
+        # @see Measure Container for adding notes
         class PitchedNote < Note
+          # Creates a pitched note.
+          #
+          # @param _step [String, nil] step as positional parameter (alternative to keyword)
+          # @param step [String, nil] diatonic step: 'C', 'D', 'E', 'F', 'G', 'A', 'B'
+          # @param alter [Integer, nil] semitone alteration: -2 (double flat), -1 (flat),
+          #   0 (natural), +1 (sharp), +2 (double sharp)
+          # @param octave [Integer] octave number (scientific pitch notation, middle C = 4)
+          #
+          # @param (see Note#initialize) All Note parameters are supported
+          #
+          # @example C natural in octave 4, quarter note
+          #   PitchedNote.new('C', octave: 4, duration: 4, type: 'quarter')
+          #
+          # @example F sharp in octave 5, eighth note
+          #   PitchedNote.new('F', alter: 1, octave: 5, duration: 2, type: 'eighth',
+          #                   accidental: 'sharp')
+          #
+          # @example B flat with keyword syntax
+          #   PitchedNote.new(step: 'B', alter: -1, octave: 4, duration: 4,
+          #                   type: 'quarter', accidental: 'flat')
+          #
+          # For detailed parameter documentation, see {Note#initialize}
           def initialize(_step = nil, step: nil, alter: nil, octave:,
                          pizzicato: nil, # true
                          grace: nil, # true
@@ -104,12 +198,42 @@ module Musa
             super
           end
 
+          # Step builder/setter.
+          # @overload step(value)
+          #   Sets step via DSL
+          #   @param value [String] diatonic step ('C'-'G')
+          # @overload step=(value)
+          #   Sets step via assignment
+          #   @param value [String] diatonic step ('C'-'G')
           attr_simple_builder :step
+
+          # Alter builder/setter.
+          # @overload alter(value)
+          #   Sets alteration via DSL
+          #   @param value [Integer] semitone alteration (-2 to +2)
+          # @overload alter=(value)
+          #   Sets alteration via assignment
+          #   @param value [Integer] semitone alteration (-2 to +2)
           attr_simple_builder :alter
+
+          # Octave builder/setter.
+          # @overload octave(value)
+          #   Sets octave via DSL
+          #   @param value [Integer] octave number
+          # @overload octave=(value)
+          #   Sets octave via assignment
+          #   @param value [Integer] octave number
           attr_simple_builder :octave
 
           private
 
+          # Outputs the pitch 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
 

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

@@ -4,7 +4,83 @@ module Musa
   module MusicXML
     module Builder
       module Internal
+        # Rest (silence) with specified duration or full measure.
+        #
+        # Rest represents musical silence. It extends {Note} with rest-specific
+        # features, particularly the measure rest attribute for whole-measure silences.
+        #
+        # ## Types of Rests
+        #
+        # ### Regular Rests
+        # Rests with explicit duration and type (whole, half, quarter, eighth, etc.):
+        #
+        #     Rest.new(duration: 4, type: 'half')
+        #     Rest.new(duration: 1, type: 'sixteenth', dots: 1)
+        #
+        # ### Measure Rests
+        # Full-measure rests that automatically fill the entire measure regardless
+        # of time signature:
+        #
+        #     Rest.new(duration: 8, type: 'whole', measure: true)
+        #
+        # The `measure: true` attribute tells notation software to center the rest
+        # and adjust its appearance based on the time signature.
+        #
+        # ## Dotted Rests
+        #
+        # Like notes, rests can have augmentation dots:
+        #
+        #     Rest.new(duration: 3, type: 'quarter', dots: 1)  # Dotted quarter
+        #     Rest.new(duration: 7, type: 'half', dots: 2)     # Double-dotted half
+        #
+        # ## Multi-Voice Rests
+        #
+        # In polyphonic music, rests can be assigned to specific voices:
+        #
+        #     Rest.new(duration: 2, type: 'quarter', voice: 2)
+        #
+        # ## Usage
+        #
+        # Created via Measure#add_rest or Measure#rest:
+        #
+        #     measure.rest duration: 4, type: 'half'
+        #     measure.add_rest duration: 8, type: 'whole', measure: true
+        #
+        # @example Quarter rest
+        #   Rest.new(duration: 2, type: 'quarter')
+        #
+        # @example Measure rest (whole measure)
+        #   Rest.new(duration: 8, type: 'whole', measure: true)
+        #
+        # @example Dotted eighth rest
+        #   Rest.new(duration: 3, type: 'eighth', dots: 1)
+        #
+        # @example Rest in specific voice
+        #   Rest.new(duration: 4, type: 'half', voice: 2)
+        #
+        # @example Rest with fermata
+        #   Rest.new(duration: 8, type: 'whole', fermata: true)
+        #
+        # @see Note Base class with all notation attributes
+        # @see PitchedNote Pitched notes
+        # @see UnpitchedNote Unpitched percussion
+        # @see Measure Container for adding rests
         class Rest < Note
+          # Creates a rest.
+          #
+          # @param measure [Boolean, nil] measure rest (fills entire measure)
+          # @param (see Note#initialize) All Note parameters are supported
+          #
+          # @example Quarter rest
+          #   Rest.new(duration: 2, type: 'quarter')
+          #
+          # @example Whole measure rest
+          #   Rest.new(duration: 8, type: 'whole', measure: true)
+          #
+          # @example Dotted eighth rest in voice 2
+          #   Rest.new(duration: 3, type: 'eighth', dots: 1, voice: 2)
+          #
+          # For detailed parameter documentation, see {Note#initialize}
           def initialize(pizzicato: nil, # true
                          measure: nil, # true
                          grace: nil, # true
@@ -102,10 +178,27 @@ module Musa
             super
           end
 
+          # Measure rest builder/setter.
+          #
+          # Indicates whether this is a full-measure rest.
+          #
+          # @overload measure(value)
+          #   Sets measure rest via DSL
+          #   @param value [Boolean] true for measure rest
+          # @overload measure=(value)
+          #   Sets measure rest via assignment
+          #   @param value [Boolean] true for measure rest
           attr_simple_builder :measure
 
           private
 
+          # Outputs the rest 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}<rest #{"measure=\"yes\"" if @measure}/>"

data/lib/musa-dsl/musicxml/builder/score-partwise.rb

@@ -12,12 +12,137 @@ require_relative 'helper'
 module Musa
   module MusicXML
     module Builder
+      # Main entry point for creating MusicXML scores.
+      #
+      # ScorePartwise represents the root `<score-partwise>` element of a MusicXML 3.0
+      # document. It contains metadata (work info, creators, rights), part definitions,
+      # and the actual musical content organized by parts and measures.
+      #
+      # ## Structure
+      #
+      # A ScorePartwise document contains:
+      #
+      # - **Metadata**: work title/number, movement title/number, creators, rights
+      # - **Part List**: part and part-group declarations with names/abbreviations
+      # - **Parts**: actual musical content (measures with notes, dynamics, etc.)
+      #
+      # ## Usage Patterns
+      #
+      # ### Constructor Style
+      #
+      # Set properties via constructor parameters and use `add_*` methods:
+      #
+      #     score = ScorePartwise.new(
+      #       work_title: "Symphony No. 1",
+      #       creators: { composer: "Composer Name" }
+      #     )
+      #     part = score.add_part(:p1, name: "Violin")
+      #     measure = part.add_measure(divisions: 2)
+      #
+      # ### DSL Style
+      #
+      # Use blocks with method names as setters/builders:
+      #
+      #     score = ScorePartwise.new do
+      #       work_title "Symphony No. 1"
+      #       creators composer: "Composer Name"
+      #       part :p1, name: "Violin" do
+      #         measure do
+      #           # measure content
+      #         end
+      #       end
+      #     end
+      #
+      # ## Part Groups
+      #
+      # Parts can be organized into groups (for orchestral sections, etc.):
+      #
+      #     score.add_group 1, type: 'start', name: "Strings"
+      #     score.add_part :p1, name: "Violin I"
+      #     score.add_part :p2, name: "Violin II"
+      #     score.add_group 1, type: 'stop'
+      #
+      # ## XML Output
+      #
+      # Generate MusicXML 3.0 compliant XML:
+      #
+      #     File.open('score.xml', 'w') do |f|
+      #       score.to_xml(f)
+      #     end
+      #
+      #     # Or get as string:
+      #     xml_string = score.to_xml.string
+      #
+      # @example Complete score with two parts
+      #   score = ScorePartwise.new do
+      #     work_title "Duet"
+      #     creators composer: "J. Composer"
+      #     encoding_date DateTime.new(2024, 1, 1)
+      #
+      #     part :p1, name: "Flute" do
+      #       measure do
+      #         attributes do
+      #           divisions 4
+      #           key fifths: 1  # G major
+      #           time beats: 3, beat_type: 4
+      #           clef sign: 'G', line: 2
+      #         end
+      #         pitch 'G', octave: 4, duration: 4, type: 'quarter'
+      #         pitch 'A', octave: 4, duration: 4, type: 'quarter'
+      #         pitch 'B', octave: 4, duration: 4, type: 'quarter'
+      #       end
+      #     end
+      #
+      #     part :p2, name: "Piano" do
+      #       measure do
+      #         attributes do
+      #           divisions 4
+      #           key fifths: 1
+      #           time beats: 3, beat_type: 4
+      #           clef sign: 'G', line: 2
+      #         end
+      #         pitch 'D', octave: 4, duration: 12, type: 'half', dots: 1
+      #       end
+      #     end
+      #   end
+      #
+      # @see Internal::Part Part implementation
+      # @see Internal::PartGroup Part grouping
+      # @see Internal::Measure Measure implementation
       class ScorePartwise
         extend Musa::Extension::AttributeBuilder
         include Musa::Extension::With
 
         include Internal::Helper::ToXML
 
+        # Creates a new MusicXML score.
+        #
+        # @param work_number [Integer, nil] opus or catalog number
+        # @param work_title [String, nil] title of the work
+        # @param movement_number [Integer, String, nil] movement number
+        # @param movement_title [String, nil] movement title
+        # @param encoding_date [DateTime, nil] encoding date (default: now)
+        # @param creators [Hash{Symbol => String}, nil] creators by type (e.g., composer: "Name")
+        # @param rights [Hash{Symbol => String}, nil] rights by type (e.g., lyrics: "Name")
+        # @yield Optional DSL block for building score structure
+        #
+        # @example With metadata in constructor
+        #   ScorePartwise.new(
+        #     work_title: "Sonata in C",
+        #     work_number: 1,
+        #     movement_title: "Allegro",
+        #     creators: { composer: "Mozart", arranger: "Smith" },
+        #     rights: { lyrics: "Public Domain" }
+        #   )
+        #
+        # @example With DSL block
+        #   ScorePartwise.new do
+        #     work_title "Sonata in C"
+        #     creators composer: "Mozart"
+        #     part :p1, name: "Piano" do
+        #       # ...
+        #     end
+        #   end
         def initialize(work_number: nil, work_title: nil,
                        movement_number: nil, movement_title: nil,
                        encoding_date: nil,
@@ -44,17 +169,117 @@ module Musa
           with &block if block_given?
         end
 
+        # Work title builder/setter.
+        #
+        # @overload work_title(value)
+        #   Sets work title via DSL
+        #   @param value [String] work title
+        # @overload work_title=(value)
+        #   Sets work title via assignment
+        #   @param value [String] work title
         attr_simple_builder :work_title
+
+        # Work number builder/setter.
+        #
+        # @overload work_number(value)
+        #   Sets work number via DSL
+        #   @param value [Integer] work number
+        # @overload work_number=(value)
+        #   Sets work number via assignment
+        #   @param value [Integer] work number
         attr_simple_builder :work_number
 
+        # Movement title builder/setter.
+        #
+        # @overload movement_title(value)
+        #   Sets movement title via DSL
+        #   @param value [String] movement title
+        # @overload movement_title=(value)
+        #   Sets movement title via assignment
+        #   @param value [String] movement title
         attr_simple_builder :movement_title
+
+        # Movement number builder/setter.
+        #
+        # @overload movement_number(value)
+        #   Sets movement number via DSL
+        #   @param value [Integer, String] movement number
+        # @overload movement_number=(value)
+        #   Sets movement number via assignment
+        #   @param value [Integer, String] movement number
         attr_simple_builder :movement_number
 
+        # Encoding date builder/setter.
+        #
+        # @overload encoding_date(value)
+        #   Sets encoding date via DSL
+        #   @param value [DateTime] encoding date
+        # @overload encoding_date=(value)
+        #   Sets encoding date via assignment
+        #   @param value [DateTime] encoding date
         attr_simple_builder :encoding_date
 
+        # Adds rights information (single or multiple).
+        #
+        # Rights specify copyright, licensing, or attribution information.
+        #
+        # @overload rights(hash)
+        #   Adds multiple rights via hash (DSL style)
+        #   @param hash [Hash{Symbol => String}] rights by type
+        # @overload add_rights(type, name)
+        #   Adds single rights entry (method style)
+        #   @param type [Symbol, String] rights type (e.g., :lyrics, :arrangement)
+        #   @param name [String] rights holder name
+        #
+        # @example DSL style
+        #   score.rights lyrics: "John Doe", music: "Jane Smith"
+        #
+        # @example Method style
+        #   score.add_rights :lyrics, "John Doe"
+        #   score.add_rights :music, "Jane Smith"
         attr_tuple_adder_to_array :rights, Internal::Rights, plural: :rights
+
+        # Adds creator information (single or multiple).
+        #
+        # Creators specify who created various aspects of the work.
+        #
+        # @overload creators(hash)
+        #   Adds multiple creators via hash (DSL style)
+        #   @param hash [Hash{Symbol => String}] creators by type
+        # @overload add_creator(type, name)
+        #   Adds single creator entry (method style)
+        #   @param type [Symbol, String] creator type (e.g., :composer, :lyricist, :arranger)
+        #   @param name [String] creator name
+        #
+        # @example DSL style
+        #   score.creators composer: "Mozart", lyricist: "Da Ponte"
+        #
+        # @example Method style
+        #   score.add_creator :composer, "Mozart"
+        #   score.add_creator :lyricist, "Da Ponte"
         attr_tuple_adder_to_array :creator, Internal::Creator
 
+        # Adds a part to the score.
+        #
+        # Parts represent individual instruments or voices in the score. Each part
+        # contains measures with musical content.
+        #
+        # @option name [String] full part name (displayed in score)
+        # @option abbreviation [String, nil] abbreviated name (for subsequent systems)
+        # @yield Optional DSL block for defining measures
+        # @return [Internal::Part] the created part
+        #
+        # @example DSL style
+        #   score.part :p1, name: "Violin I", abbreviation: "Vln. I" do
+        #     measure do
+        #       pitch 'A', octave: 4, duration: 4, type: 'quarter'
+        #     end
+        #   end
+        #
+        # @example Method style
+        #   part = score.add_part(:p1, name: "Violin I", abbreviation: "Vln. I")
+        #   measure = part.add_measure
+        #   measure.add_pitch step: 'A', octave: 4, duration: 4, type: 'quarter'
         attr_complex_adder_to_custom :part, variable: :@parts do |id, name:, abbreviation: nil, &block|
           Internal::Part.new(id, name: name, abbreviation: abbreviation, &block).tap do |part|
             @parts[id] = part
@@ -62,17 +287,64 @@ module Musa
           end
         end
 
+        # Adds a part group to organize parts.
+        #
+        # Part groups bracket multiple parts together (e.g., string section, choir).
+        # Groups are defined by matching start/stop pairs with the same number.
+        #
+        # @option type [String] 'start' or 'stop'
+        # @option name [String, nil] group name (displayed on bracket)
+        # @option abbreviation [String, nil] abbreviated group name
+        # @option symbol [String, nil] bracket symbol (e.g., 'bracket', 'brace')
+        # @option group_barline [Boolean, String, nil] whether barlines connect across group
+        # @option group_time [Boolean, String, nil] whether time signatures are shared
+        # @return [Internal::PartGroup] the created group
+        #
+        # @example Bracketing string section
+        #   score.add_group 1, type: 'start', name: "Strings", symbol: 'bracket'
+        #   score.add_part :p1, name: "Violin I"
+        #   score.add_part :p2, name: "Violin II"
+        #   score.add_part :p3, name: "Viola"
+        #   score.add_group 1, type: 'stop'
+        #
+        # @example Nested groups
+        #   score.add_group 1, type: 'start', name: "Orchestra"
+        #   score.add_group 2, type: 'start', name: "Woodwinds"
+        #   score.add_part :p1, name: "Flute"
+        #   score.add_part :p2, name: "Oboe"
+        #   score.add_group 2, type: 'stop'
+        #   score.add_group 1, type: 'stop'
         attr_complex_adder_to_custom :group do |*parameters, **key_parameters|
           Internal::PartGroup.new(*parameters, **key_parameters).tap do |group|
             @groups_and_parts << group
           end
         end
 
+        # Generates the complete MusicXML document structure.
+        #
+        # Creates a MusicXML 3.0 Partwise document with:
+        # - XML declaration and DOCTYPE
+        # - Work and movement metadata
+        # - Identification section (creators, rights, encoding info)
+        # - Part list (part and group declarations)
+        # - Part content (measures with notes)
+        #
+        # The encoding section automatically includes:
+        # - Encoding date (from @encoding_date)
+        # - Software attribution: "MusaDSL: MusicXML output formatter"
+        #
+        # @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:)
           io.puts "#{tabs}<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"no\"?>"
           io.puts "#{tabs}<!DOCTYPE score-partwise PUBLIC \"-//Recordare//DTD MusicXML 3.0 Partwise//EN\" \"http://www.musicxml.org/dtds/partwise.dtd\">"
           io.puts "#{tabs}<score-partwise version=\"3.0\">"
 
+          # Work section (optional)
           if @work_number || @work_title
             io.puts"#{tabs}\t<work>"
             io.puts"#{tabs}\t\t<work-number>#{@work_number.to_i}</work-number>" if @work_number
@@ -80,9 +352,11 @@ module Musa
             io.puts"#{tabs}\t</work>"
           end
 
+          # Movement metadata (optional)
           io.puts"#{tabs}\t<movement-number>#{@movement_number.to_i}</movement-number>" if @movement_number
           io.puts"#{tabs}\t<movement-title>#{@movement_title}</movement-title>" if @movement_title
 
+          # Identification section (required)
           io.puts "#{tabs}\t<identification>"
 
           @creators.each do |creator|
@@ -100,12 +374,14 @@ module Musa
 
           io.puts "#{tabs}\t</identification>"
 
+          # Part list section (required)
           io.puts "#{tabs}\t<part-list>"
           @groups_and_parts.each do |group_or_part|
             group_or_part.header_to_xml(io, indent: indent + 2)
           end
           io.puts "#{tabs}\t</part-list>"
 
+          # Parts content (measures with notes)
           @parts.each_value do |part|
             part.to_xml(io, indent: indent + 1)
           end

data/lib/musa-dsl/musicxml/builder/typed-text.rb

@@ -4,17 +4,46 @@ module Musa
   module MusicXML
     module Builder
       module Internal
+        # Base class for typed text elements (creators, rights).
+        #
+        # TypedText represents MusicXML elements that have a type attribute and
+        # text content, such as `<creator type="composer">Name</creator>`.
+        #
+        # This is a private base class used by {Creator} and {Rights}.
+        #
+        # @api private
         class TypedText
           include Helper::ToXML
 
+          # Creates a typed text element.
+          #
+          # @param type [String, Symbol, nil] element type attribute
+          # @param text [String] text content
           def initialize(type = nil, text)
             @type = type
             @text = text
           end
 
-          attr_accessor :type, :text
+          # Type attribute value.
+          # @return [String, Symbol, nil]
+          attr_accessor :type
+
+          # Text content.
+          # @return [String]
+          attr_accessor :text
+
+          # XML tag name (set by subclasses).
+          # @return [String]
           attr_reader :tag
 
+          # Generates XML for this typed text 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.puts "#{tabs}<#{tag}#{" type=\"#{@type}\"" if @type}>#{@text}</#{tag}>"
           end
@@ -22,14 +51,46 @@ module Musa
 
         private_constant :TypedText
 
+        # Creator metadata for MusicXML identification section.
+        #
+        # Represents a `<creator>` element specifying who created various aspects
+        # of the work (composer, lyricist, arranger, etc.).
+        #
+        # @example
+        #   creator = Creator.new(:composer, "Ludwig van Beethoven")
+        #   creator.to_xml  # => <creator type="composer">Ludwig van Beethoven</creator>
         class Creator < TypedText
+          # Creates a creator entry.
+          #
+          # @param type [String, Symbol] creator type (e.g., :composer, :lyricist, :arranger)
+          # @param name [String] creator's name
+          #
+          # @example
+          #   Creator.new(:composer, "Mozart")
+          #   Creator.new(:lyricist, "Da Ponte")
           def initialize(type, name)
             @tag = 'creator'
             super type, name
           end
         end
 
+        # Rights metadata for MusicXML identification section.
+        #
+        # Represents a `<rights>` element specifying copyright, licensing, or
+        # attribution information.
+        #
+        # @example
+        #   rights = Rights.new(:lyrics, "Copyright 2024 Publisher Name")
+        #   rights.to_xml  # => <rights type="lyrics">Copyright 2024 Publisher Name</rights>
         class Rights < TypedText
+          # Creates a rights entry.
+          #
+          # @param type [String, Symbol] rights type (e.g., :lyrics, :music, :arrangement)
+          # @param name [String] rights statement or holder name
+          #
+          # @example
+          #   Rights.new(:music, "Copyright 2024 ACME Publishing")
+          #   Rights.new(:lyrics, "Public Domain")
           def initialize(type, name)
             @tag = 'rights'
             super type, name