faker 2.3.0 → 2.7.0

data/lib/faker/default/time.rb

@@ -14,8 +14,31 @@ module Faker
 
     class << self
       # rubocop:disable Metrics/ParameterLists
+      # rubocop:disable Style/AsciiComments
+
+      ##
+      # Produce a random time between two times.
+      #
+      # @param from [Time, Date, DateTime] The start of the usable time range.
+      # @param to [Time, Date, DateTime] The end of the usable time range.
+      # @param format [Symbol] The name of a DateTime format to use.
+      # @return [Time]
+      #
+      # @example
+      #   # Random Stringified time between two times, formatted to the specified I18n format
+      #   # (Examples are from a Rails console with rails-i18n 5.1.1 defaults loaded)
+      #   I18n.locale = 'en-US'
+      #   Faker::Time.between(from: DateTime.now - 1, to: DateTime.now, format: :default) #=> "Tue, 16 Oct 2018 10:48:27 AM -05:00"
+      #   Faker::Time.between(from: DateTime.now - 1, to: DateTime.now, format: :short) #=> "15 Oct 10:48 AM"
+      #   Faker::Time.between(from: DateTime.now - 1, to: DateTime.now, format: :long) #=> "October 15, 2018 10:48 AM"
+      #
+      #   I18n.locale = 'ja'
+      #   Faker::Time.between(from: DateTime.now - 1, to: DateTime.now, format: :default) #=> "2018/10/15 10:48:27"
+      #   Faker::Time.between(from: DateTime.now - 1, to: DateTime.now, format: :short) #=> "18/10/15 10:48"
+      #   Faker::Time.between(from: DateTime.now - 1, to: DateTime.now, format: :long) #=> "2018年10月16日(火) 10時48分27秒 -0500"
+      #
+      # @faker.version 1.5.0
       def between(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, legacy_format = NOT_GIVEN, from:, to:, format: nil)
-        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :from if legacy_from != NOT_GIVEN
           keywords << :to if legacy_to != NOT_GIVEN
@@ -28,10 +51,37 @@ module Faker
         time = Faker::Base.rand_in_range(from, to)
         time_with_format(time, format)
       end
-
-      # rubocop:disable Metrics/ParameterLists
+      # rubocop:enable Style/AsciiComments
+
+      ##
+      # Produce a random time between two dates.
+      #
+      # @param from [Date] The start of the usable time range.
+      # @param to [Date] The end of the usable time range.
+      # @param period [Symbol] The time of day, if any. See {TIME_RANGES}.
+      # @param format [Symbol] The name of a DateTime format to use.
+      # @return [Time]
+      #
+      # @example
+      #   Faker::Time.between_dates(from: Date.today - 1, to: Date.today, period: :all)
+      #     #=> "2014-09-19 07:03:30 -0700"
+      #   Faker::Time.between_dates(from: Date.today - 1, to: Date.today, period: :day)
+      #     #=> "2014-09-18 16:28:13 -0700"
+      #   Faker::Time.between_dates(from: Date.today - 1, to: Date.today, period: :night)
+      #     #=> "2014-09-20 19:39:38 -0700"
+      #   Faker::Time.between_dates(from: Date.today - 1, to: Date.today, period: :morning)
+      #     #=> "2014-09-19 08:07:52 -0700"
+      #   Faker::Time.between_dates(from: Date.today - 1, to: Date.today, period: :afternoon)
+      #     #=> "2014-09-18 12:10:34 -0700"
+      #   Faker::Time.between_dates(from: Date.today - 1, to: Date.today, period: :evening)
+      #     #=> "2014-09-19 20:21:03 -0700"
+      #   Faker::Time.between_dates(from: Date.today - 1, to: Date.today, period: :midnight)
+      #     #=> "2014-09-20 00:40:14 -0700"
+      #   Faker::Time.between_dates(from: Date.today - 5, to: Date.today + 5, period: :afternoon, format: :default)
+      #     #=> "Fri, 19 Oct 2018 15:17:46 -0500"
+      #
+      # @faker.version 1.0.0
       def between_dates(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, legacy_period = NOT_GIVEN, legacy_format = NOT_GIVEN, from:, to:, period: :all, format: nil)
-        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :from if legacy_from != NOT_GIVEN
           keywords << :to if legacy_to != NOT_GIVEN
@@ -44,9 +94,22 @@ module Faker
         time_with_format(time, format)
       end
 
-      # rubocop:disable Metrics/ParameterLists
+      ##
+      # Produce a random time in the future (up to N days).
+      #
+      # @param days [Integer] The maximum number of days to go into the future.
+      # @param period [Symbol] The time of day, if any. See {TIME_RANGES}.
+      # @param format [Symbol] The name of a DateTime format to use.
+      # @return [Time]
+      #
+      # @example
+      #   Faker::Time.forward(days: 23, period: :morning)
+      #     # => "2014-09-26 06:54:47 -0700"
+      #   Faker::Time.forward(days: 5,  period: :evening, format: :long)
+      #     #=> "October 21, 2018 20:47"
+      #
+      # @faker.version 1.5.0
       def forward(legacy_days = NOT_GIVEN, legacy_period = NOT_GIVEN, legacy_format = NOT_GIVEN, days: 365, period: :all, format: nil)
-        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :days if legacy_days != NOT_GIVEN
           keywords << :period if legacy_period != NOT_GIVEN
@@ -56,9 +119,22 @@ module Faker
         time_with_format(date_with_random_time(Faker::Date.forward(days: days), period), format)
       end
 
-      # rubocop:disable Metrics/ParameterLists
+      ##
+      # Produce a random time in the past (up to N days).
+      #
+      # @param days [Integer] The maximum number of days to go into the past.
+      # @param period [Symbol] The time of day, if any. See {TIME_RANGES}.
+      # @param format [Symbol] The name of a DateTime format to use.
+      # @return [Time]
+      #
+      # @example
+      #   Faker::Time.backward(days: 14, period: :evening)
+      #     #=> "2014-09-17 19:56:33 -0700"
+      #   Faker::Time.backward(days: 5, period: :morning, format: :short)
+      #     #=> "14 Oct 07:44"
+      #
+      # @faker.version 1.5.0
       def backward(legacy_days = NOT_GIVEN, legacy_period = NOT_GIVEN, legacy_format = NOT_GIVEN, days: 365, period: :all, format: nil)
-        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :days if legacy_days != NOT_GIVEN
           keywords << :period if legacy_period != NOT_GIVEN
@@ -67,6 +143,7 @@ module Faker
 
         time_with_format(date_with_random_time(Faker::Date.backward(days: days), period), format)
       end
+      # rubocop:enable Metrics/ParameterLists
 
       private
 

data/lib/faker/default/world_cup.rb

@@ -3,18 +3,56 @@
 module Faker
   class WorldCup < Base
     class << self
+      ##
+      # Produces a national team name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::WorldCup.team #=> "Iran"
+      #
+      # @faker.version 1.9.0
       def team
         fetch('world_cup.teams')
       end
 
+      ##
+      # Produces a city name hosting the World Cup match.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::WorldCup.city #=> "Moscow"
+      #
+      # @faker.version next
       def city
         fetch('world_cup.cities')
       end
 
+      ##
+      # Produces the name of a stadium that has hosted a World Cup match.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::WorldCup.stadium #=> "Rostov Arena"
+      #
+      # @faker.version next
       def stadium
         fetch('world_cup.stadiums')
       end
 
+      ##
+      # Produces a random national team name from a group. See below examples
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::WorldCup.group(group: 'group_B') #=> "Spain"
+      # @example
+      #   Faker::WorldCup.group #=> "Russia"
+      #
+      # @faker.version next
       def group(legacy_group = NOT_GIVEN, group: 'group_A')
         warn_for_deprecated_arguments do |keywords|
           keywords << :group if legacy_group != NOT_GIVEN
@@ -23,6 +61,18 @@ module Faker
         fetch("world_cup.groups.#{group}")
       end
 
+      ##
+      # Produces a random name from national team roster. See below examples.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::WorldCup.roster #=> "Hector Cuper"
+      #
+      # @example
+      #   Faker::WorldCup.roster(country: 'Spain', type: 'forwards') #=> "Diego Costa"
+      #
+      # @faker.version next
       def roster(legacy_country = NOT_GIVEN, legacy_type = NOT_GIVEN, country: 'Egypt', type: 'coach')
         warn_for_deprecated_arguments do |keywords|
           keywords << :country if legacy_country != NOT_GIVEN

data/lib/faker/games/dota.rb

@@ -4,22 +4,69 @@ module Faker
   class Games
     class Dota < Base
       class << self
+        ##
+        # Produces the name of a hero from Dota.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Games::Dota.hero #=> "Abaddon"
+        #
+        # @faker.version 1.9.0
         def hero
           fetch('games.dota.hero')
         end
 
+        ##
+        # Produces the name of an item from Dota.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Games::Dota.item #=> "Armlet of Mordiggian"
+        #
+        # @faker.version 1.9.0
         def item
           fetch('games.dota.item')
         end
 
+        ##
+        # Produces the name of a professional Dota team.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Games::Dota.team #=> "Evil Geniuses"
+        #
+        # @faker.version 1.9.0
         def team
           fetch('games.dota.team')
         end
 
+        ##
+        # Produces the name of a professional Dota player.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Games::Dota.player #=> "Dendi"
+        #
+        # @faker.version 1.9.0
         def player
           fetch('games.dota.player')
         end
 
+        ##
+        # Produces the name of a hero from Dota.
+        #
+        # @param hero [String] The name of a Dota hero.
+        # @return [String]
+        #
+        # @example
+        #   Faker::Games::Dota.quote #=> "You have called death upon yourself."
+        #   Faker::Games::Dota.quote(hero: 'alchemist') #=> "Better living through alchemy!"
+        #
+        # @faker.version 1.9.0
         def quote(legacy_hero = NOT_GIVEN, hero: 'abaddon')
           warn_for_deprecated_arguments do |keywords|
             keywords << :hero if legacy_hero != NOT_GIVEN

data/lib/faker/games/heroes.rb

@@ -4,14 +4,41 @@ module Faker
   class Games
     class Heroes < Base
       class << self
+        ##
+        # Produces the name of a hero from Heroes 3.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Games::Heroes.name #=> "Christian"
+        #
+        # @faker.version 1.9.2
         def name
           fetch('heroes.names')
         end
 
+        ##
+        # Produces the name of a specialty from Heroes 3.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Games::Heroes.specialty #=> "Ballista"
+        #
+        # @faker.version 1.9.2
         def specialty
           fetch('heroes.specialties')
         end
 
+        ##
+        # Produces the name of a class from Heroes 3.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Games::Heroes.klass #=> "Knight"
+        #
+        # @faker.version 1.9.2
         def klass
           fetch('heroes.klasses')
         end

data/lib/faker/games/heroes_of_the_storm.rb

@@ -4,18 +4,54 @@ module Faker
   class Games
     class HeroesOfTheStorm < Base
       class << self
+        ##
+        # Produces a battleground from Heroes of the Storm.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Games::HeroesOfTheStorm.battleground #=> "Towers of Doom"
+        #
+        # @faker.version 1.9.2
         def battleground
           fetch('heroes_of_the_storm.battlegrounds')
         end
 
+        ##
+        # Produces a class from Heroes of the Storm.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Games::HeroesOfTheStorm.class #=> "Support"
+        #
+        # @faker.version 1.9.2
         def class
           fetch('heroes_of_the_storm.classes')
         end
 
+        ##
+        # Produces a hero from Heroes of the Storm.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Games::HeroesOfTheStorm.hero #=> "Illidan"
+        #
+        # @faker.version 1.9.2
         def hero
           fetch('heroes_of_the_storm.heroes')
         end
 
+        ##
+        # Produces a quote from Heroes of the Storm.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Games::HeroesOfTheStorm.quote #=> "MEAT!!!"
+        #
+        # @faker.version 1.9.2
         def quote
           fetch('heroes_of_the_storm.quotes')
         end

data/lib/faker/games/league_of_legends.rb

@@ -4,26 +4,80 @@ module Faker
   class Games
     class LeagueOfLegends < Base
       class << self
+        ##
+        # Produces the name of a champion from League of Legends.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Games::LeagueOfLegends.champion #=> "Jarvan IV"
+        #
+        # @faker.version 1.8.0
         def champion
           fetch('games.league_of_legends.champion')
         end
 
+        ##
+        # Produces a location from League of Legends.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Games::LeagueOfLegends.location #=> "Demacia"
+        #
+        # @faker.version 1.8.0
         def location
           fetch('games.league_of_legends.location')
         end
 
+        ##
+        # Produces a quote from League of Legends.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Games::LeagueOfLegends.quote #=> "Purge the unjust."
+        #
+        # @faker.version 1.8.0
         def quote
           fetch('games.league_of_legends.quote')
         end
 
+        ##
+        # Produces a summoner spell from League of Legends.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Games::LeagueOfLegends.summoner_spell #=> "Flash"
+        #
+        # @faker.version 1.8.0
         def summoner_spell
           fetch('games.league_of_legends.summoner_spell')
         end
 
+        ##
+        # Produces a mastery from League of Legends.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Games::LeagueOfLegends.masteries #=> "Double Edged Sword"
+        #
+        # @faker.version 1.8.0
         def masteries
           fetch('games.league_of_legends.masteries')
         end
 
+        ##
+        # Produces a rank from League of Legends.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Games::LeagueOfLegends.rank #=> "Bronze V"
+        #
+        # @faker.version 1.8.0
         def rank
           fetch('games.league_of_legends.rank')
         end