Add YARD docs for Faker::Music{,::Opera} (faker-ruby#1873)

* Add Faker::Music YARD docs

* Add Faker::MUsic::Opera YARD docs

lib/faker/music/music.rb

@@ -3,42 +3,123 @@
 module Faker
   class Music < Base
     class << self
+      ##
+      # Produces the name of a key/note, using letter notation.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Music.key #=> "A#"
+      #
+      # @faker.version 1.6.4
       def key
         sample(keys) + sample(key_variants)
       end
 
+      ##
+      # Produces the name of a chord, using letter notation.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Music.chord #=> "Adim7"
+      #
+      # @faker.version 1.6.4
       def chord
         key + sample(chord_types)
       end
 
+      ##
+      # Produces the name of an instrument.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Music.instrument #=> "Acoustic Guitar"
+      #
+      # @faker.version 1.6.4
       def instrument
         fetch('music.instruments')
       end
 
+      ##
+      # Produces an array of the letter names of musical notes, without accidentals.
+      #
+      # @return [Array<String>]
+      #
+      # @faker.version 1.6.4
       def keys
         %w[C D E F G A B]
       end
 
+      ##
+      # Produces an array of accidentals (with "natural" denoted as an empty string).
+      #
+      # @return [Array<String>]
+      #
+      # @faker.version 1.6.4
       def key_variants
         ['b', '#', '']
       end
 
+      ##
+      # Produces an array of key types (with "major" denoted as an empty string).
+      #
+      # @return [Array<String>]
+      #
+      # @example
+      #   Faker::Music.key_types #=> ['', 'm']
+      #
+      # @faker.version 1.6.4
       def key_types
         ['', 'm']
       end
 
+      ##
+      # Produces an array of types of chords.
+      #
+      # @return [Array<String>]
+      #
+      # @faker.version 1.6.4
       def chord_types
         ['', 'maj', '6', 'maj7', 'm', 'm7', '-7', '7', 'dom7', 'dim', 'dim7', 'm7b5']
       end
 
+      ##
+      # Produces the name of a band.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Music.band #=> "The Beatles"
+      #
+      # @faker.version 1.9.1
       def band
         fetch('music.bands')
       end
 
+      ##
+      # Produces the name of an album.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Music.album #=> "Sgt. Pepper's Lonely Hearts Club"
+      #
+      # @faker.version 1.9.1
       def album
         fetch('music.albums')
       end
 
+      ##
+      # Produces the name of a musical genre.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Music.genre #=> "Rock"
+      #
+      # @faker.version 1.9.1
       def genre
         fetch('music.genres')
       end

lib/faker/music/opera.rb

@@ -5,18 +5,54 @@ module Faker
   class Music
     class Opera < Base
       class << self
+        ##
+        # Produces the title of an opera by Giuseppe Verdi.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Music::Opera.verdi #=> "Il Trovatore"
+        #
+        # @faker.version 1.9.4
         def verdi
           fetch('opera.italian.by_giuseppe_verdi')
         end
 
+        ##
+        # Produces the title of an opera by Gioacchino Rossini.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Music::Opera.rossini #=> "Il Barbiere di Siviglia"
+        #
+        # @faker.version 1.9.4
         def rossini
           fetch('opera.italian.by_gioacchino_rossini')
         end
 
+        ##
+        # Produces the title of an opera by Gaetano Donizetti.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Music::Opera.donizetti #=> "Lucia di Lammermoor"
+        #
+        # @faker.version 1.9.4
         def donizetti
           fetch('opera.italian.by_gaetano_donizetti')
         end
 
+        ##
+        # Produces the title of an opera by Vincenzo Bellini.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Music::Opera.bellini #=> "Norma"
+        #
+        # @faker.version 1.9.4
         def bellini
           fetch('opera.italian.by_vincenzo_bellini')
         end