faker 2.7.0 → 2.8.1

data/lib/faker/default/esport.rb

@@ -3,22 +3,67 @@
 module Faker
   class Esport < Base
     class << self
+      ##
+      # Produces the name of a professional eSports player.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Esport.player #=> "Crimsix"
+      #
+      # @faker.version 1.7.0
       def player
         fetch('esport.players')
       end
 
+      ##
+      # Produces the name of an eSports team.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Esport.team #=> "CLG"
+      #
+      # @faker.version 1.7.0
       def team
         fetch('esport.teams')
       end
 
+      ##
+      # Produces the name of an eSports league.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Esport.league #=> "IEM"
+      #
+      # @faker.version 1.7.0
       def league
         fetch('esport.leagues')
       end
 
+      ##
+      # Produces the name of an eSports event.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Esport.event #=> "ESL Cologne"
+      #
+      # @faker.version 1.7.0
       def event
         fetch('esport.events')
       end
 
+      ##
+      # Produces the name of a game played as an eSport.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Esport.game #=> "Dota 2"
+      #
+      # @faker.version 1.7.0
       def game
         fetch('esport.games')
       end

data/lib/faker/default/fillmurray.rb

@@ -4,8 +4,29 @@ module Faker
   class Fillmurray < Base
     class << self
       # rubocop:disable Metrics/ParameterLists
+
+      ##
+      # Produces the URL of an image from Fill Murray, a site which hosts
+      # exclusively photographs of actor Bill Murray.
+      #
+      # @param grayscale [Boolean] Whether to return a grayscale image.
+      # @param width [Integer] The iamage width.
+      # @param height [Integer] The image height.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Fillmurray.image #=> "https://www.fillmurray.com/300/300"
+      #
+      # @example
+      #   Faker::Fillmurray.image(grayscale: true)
+      #     #=> "https://fillmurray.com/g/300/300"
+      #
+      # @example
+      #   Faker::Fillmurray.image(grayscale: false, width: 200, height: 400)
+      #     #=> "https://fillmurray.com/200/400"
+      #
+      # @faker.version 1.7.1
       def image(legacy_grayscale = NOT_GIVEN, legacy_width = NOT_GIVEN, legacy_height = NOT_GIVEN, grayscale: false, width: 200, height: 200)
-        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :grayscale if legacy_grayscale != NOT_GIVEN
           keywords << :width if legacy_width != NOT_GIVEN
@@ -18,6 +39,7 @@ module Faker
 
         "https://www.fillmurray.com#{'/g' if grayscale == true}/#{width}/#{height}"
       end
+      # rubocop:enable Metrics/ParameterLists
     end
   end
 end

data/lib/faker/default/food.rb

@@ -5,42 +5,106 @@ module Faker
     flexible :food
 
     class << self
-      # Retrieves a typical dish from each country
+      ##
+      # Retrieves a typical dish from each country.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Food.dish #=> "Feijoada"
+      #
+      # @faker.version 1.8.0
       def dish
         fetch('food.dish')
       end
 
+      ##
       # Retrieves a description about some dish
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Food.description #=> "Breaded fried chicken with waffles. Served with maple syrup."
+      #
+      # @faker.version 1.9.0
       def description
         fetch('food.descriptions')
       end
 
+      ##
       # Retrieves an ingredient
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Food.ingredient #=> "Olives"
+      #
+      # @faker.version 1.7.0
       def ingredient
         fetch('food.ingredients')
       end
 
+      ##
       # Retrieves a fruit
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Food.fruits #=> "Papaya"
+      #
+      # @faker.version 1.9.0
       def fruits
         fetch('food.fruits')
       end
 
+      ##
       # Retrieves a vegetable
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Food.vegetables #=> "Broccolini"
+      #
+      # @faker.version 1.9.0
       def vegetables
         fetch('food.vegetables')
       end
 
+      ##
       # Retrieves some random spice
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Food.spice #=> "Garlic Chips"
+      #
+      # @faker.version 1.7.0
       def spice
         fetch('food.spices')
       end
 
+      ##
       # Retrieves cooking measures
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Food.measurement #=> "1/3"
+      #
+      # @faker.version 1.7.0
       def measurement
         fetch('food.measurement_sizes') + ' ' + fetch('food.measurements')
       end
 
+      ##
       # Retrieves metric mesurements
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Food.metric_measurement #=> "centiliter"
+      #
+      # @faker.version 1.8.3
       def metric_measurement
         fetch('food.metric_measurements')
       end

data/lib/faker/default/internet.rb

@@ -3,16 +3,16 @@
 module Faker
   class Internet < Base
     class << self
-      def email(legacy_name = NOT_GIVEN, legacy_separators = NOT_GIVEN, name: nil, separators: nil)
+      def email(legacy_name = NOT_GIVEN, legacy_separators = NOT_GIVEN, name: nil, separators: nil, domain: nil)
         warn_for_deprecated_arguments do |keywords|
           keywords << :name if legacy_name != NOT_GIVEN
           keywords << :separators if legacy_separators != NOT_GIVEN
         end
 
         if separators
-          [username(specifier: name, separators: separators), domain_name].join('@')
+          [username(specifier: name, separators: separators), domain_name(domain: domain)].join('@')
         else
-          [username(specifier: name), domain_name].join('@')
+          [username(specifier: name), domain_name(domain: domain)].join('@')
         end
       end
 
@@ -135,15 +135,25 @@ module Faker
         temp
       end
 
-      def domain_name(legacy_subdomain = NOT_GIVEN, subdomain: false)
+      def domain_name(legacy_subdomain = NOT_GIVEN, subdomain: false, domain: nil)
         warn_for_deprecated_arguments do |keywords|
           keywords << :subdomain if legacy_subdomain != NOT_GIVEN
         end
 
         with_locale(:en) do
-          domain_elements = [Char.prepare(domain_word), domain_suffix]
-          domain_elements.unshift(Char.prepare(domain_word)) if subdomain
-          domain_elements.join('.')
+          if domain
+            domain
+              .split('.')
+              .map { |domain_part| Char.prepare(domain_part) }
+              .tap do |domain_elements|
+                domain_elements << domain_suffix if domain_elements.length < 2
+                domain_elements.unshift(Char.prepare(domain_word)) if subdomain && domain_elements.length < 3
+              end.join('.')
+          else
+            [domain_word, domain_suffix].tap do |domain_elements|
+              domain_elements.unshift(Char.prepare(domain_word)) if subdomain
+            end.join('.')
+          end
         end
       end
 

data/lib/faker/default/kpop.rb

@@ -3,26 +3,80 @@
 module Faker
   class Kpop < Base
     class << self
+      ##
+      # Produces the name of a 1990's 'OG' K-Pop group.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Kpop.i_groups #=> "Seo Taiji and Boys"
+      #
+      # @faker.version 1.8.5
       def i_groups
         fetch('kpop.i_groups')
       end
 
+      ##
+      # Produces the name of a 2000's K-Pop group.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Kpop.ii_groups #=> "Girls' Generation"
+      #
+      # @faker.version 1.8.5
       def ii_groups
         fetch('kpop.ii_groups')
       end
 
+      ##
+      # Produces the name of a 2010's K-Pop group.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Kpop.iii_groups #=> "Trouble Maker"
+      #
+      # @faker.version 1.8.5
       def iii_groups
         fetch('kpop.iii_groups')
       end
 
+      ##
+      # Produces the name of a K-Pop girl group.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Kpop.girl_groups #=> "2NE1"
+      #
+      # @faker.version 1.8.5
       def girl_groups
         fetch('kpop.girl_groups')
       end
 
+      ##
+      # Produces the name of a K-Pop boy band.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Kpop.boy_bands #=> "Exo"
+      #
+      # @faker.version 1.8.5
       def boy_bands
         fetch('kpop.boy_bands')
       end
 
+      ##
+      # Produces the name of a solo K-Pop artist.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Kpop.solo #=> "T.O.P"
+      #
+      # @faker.version 1.8.5
       def solo
         fetch('kpop.solo')
       end

data/lib/faker/default/relationship.rb

@@ -5,6 +5,15 @@ module Faker
     flexible :relationship
 
     class << self
+      ##
+      # Produces a random family relationship.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Relationship.familial #=> "Grandfather"
+      #
+      # @faker.version 1.9.2
       def familial(legacy_connection = NOT_GIVEN, connection: nil)
         warn_for_deprecated_arguments do |keywords|
           keywords << :connection if legacy_connection != NOT_GIVEN
@@ -26,18 +35,54 @@ module Faker
         fetch('relationship.familial.' + connection)
       end
 
+      ##
+      # Produces a random in-law relationship.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Relationship.in_law #=> "Brother-in-law"
+      #
+      # @faker.version 1.9.2
       def in_law
         fetch('relationship.in_law')
       end
 
+      ##
+      # Produces a random spouse relationship.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Relationship.spouse #=> "Husband"
+      #
+      # @faker.version 1.9.2
       def spouse
         fetch('relationship.spouse')
       end
 
+      ##
+      # Produces a random parent relationship.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Relationship.parent #=> "Father"
+      #
+      # @faker.version 1.9.2
       def parent
         fetch('relationship.parent')
       end
 
+      ##
+      # Produces a random sibling relationship.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Relationship.sibling #=> "Sister"
+      #
+      # @faker.version 1.9.2
       def sibling
         fetch('relationship.sibling')
       end

data/lib/faker/default/space.rb

@@ -3,59 +3,186 @@
 module Faker
   class Space < Base
     flexible :space
+
     class << self
+      ##
+      # Produces the name of a planet.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Space.planet #=> "Venus"
+      #
+      # @faker.version 1.6.4
       def planet
         fetch('space.planet')
       end
 
+      ##
+      # Produces the name of a moon.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Space.moon #=> "Europa"
+      #
+      # @faker.version 1.6.4
       def moon
         fetch('space.moon')
       end
 
+      ##
+      # Produces the name of a galaxy.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Space.galaxy #=> "Andromeda"
+      #
+      # @faker.version 1.6.4
       def galaxy
         fetch('space.galaxy')
       end
 
+      ##
+      # Produces the name of a nebula.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Space.nebula #=> "Triffid Nebula"
+      #
+      # @faker.version 1.6.4
       def nebula
         fetch('space.nebula')
       end
 
+      ##
+      # Produces the name of a star cluster.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Space.star_cluster #=> "Messier 70"
+      #
+      # @faker.version 1.6.4
       def star_cluster
         fetch('space.star_cluster')
       end
 
+      ##
+      # Produces the name of a constellation.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Space.constellation #=> "Orion"
+      #
+      # @faker.version 1.6.4
       def constellation
         fetch('space.constellation')
       end
 
+      ##
+      # Produces the name of a star.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Space.star #=> "Proxima Centauri"
+      #
+      # @faker.version 1.6.4
       def star
         fetch('space.star')
       end
 
+      ##
+      # Produces the name of a space agency.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Space.agency #=> "Japan Aerospace Exploration Agency"
+      #
+      # @faker.version 1.6.4
       def agency
         fetch('space.agency')
       end
 
+      ##
+      # Produces a space agency abbreviation.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Space.agency_abv #=> "NASA"
+      #
+      # @faker.version 1.6.4
       def agency_abv
         fetch('space.agency_abv')
       end
 
+      ##
+      # Produces the name of a NASA spacecraft.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Space.nasa_space_craft #=> "Endeavour"
+      #
+      # @faker.version 1.6.4
       def nasa_space_craft
         fetch('space.nasa_space_craft')
       end
 
+      ##
+      # Produces the name of a space company.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Space.company #=> "SpaceX"
+      #
+      # @faker.version 1.6.4
       def company
         fetch('space.company')
       end
 
+      ##
+      # Produces a distance measurement.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Space.distance_measurement #=> "15 parsecs"
+      #
+      # @faker.version 1.6.4
       def distance_measurement
         rand(10..100).to_s + ' ' + fetch('space.distance_measurement')
       end
 
+      ##
+      # Produces the name of a meteorite.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Space.meteorite #=> "Ensisheim"
+      #
+      # @faker.version 1.7.0
       def meteorite
         fetch('space.meteorite')
       end
 
+      ##
+      # Produces the name of a launch vehicle.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Space.launch_vehicle #=> "Saturn IV"
+      #
+      # @faker.version 1.9.0
       def launch_vehicle
         fetch('space.launch_vehicle')
       end