faker 2.4.0 → 2.8.1

data/lib/faker/default/date.rb

@@ -3,6 +3,18 @@
 module Faker
   class Date < Base
     class << self
+      ##
+      # Produce a random date between two dates.
+      #
+      # @param from [Date] The start of the usable date range.
+      # @param to [Date] The end of the usable date range.
+      # @return [Date]
+      #
+      # @example
+      #   Faker::Date.between(from: 2.days.ago, to: Date.today)
+      #     #=> #<Date: 2014-09-24>
+      #
+      # @faker.version 1.0.0
       def between(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from:, to:)
         warn_for_deprecated_arguments do |keywords|
           keywords << :from if legacy_from != NOT_GIVEN
@@ -16,8 +28,21 @@ module Faker
       end
 
       # rubocop:disable Metrics/ParameterLists
+
+      ##
+      # Produce a random date between two dates.
+      #
+      # @param from [Date] The start of the usable date range.
+      # @param to [Date] The end of the usable date range.
+      # @param excepted [Date] A date to exclude.
+      # @return [Date]
+      #
+      # @example
+      #   Faker::Date.between_except(from: 1.year.ago, to: 1.year.from_now, excepted: Date.today)
+      #     #=> #<Date: 2014-10-03>
+      #
+      # @faker.version 1.6.2
       def between_except(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, legacy_excepted = NOT_GIVEN, from:, to:, excepted:)
-        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :from if legacy_from != NOT_GIVEN
         end
@@ -37,7 +62,18 @@ module Faker
           break date.to_date if date != excepted
         end
       end
-
+      # rubocop:enable Metrics/ParameterLists
+
+      ##
+      # Produce a random date in the future (up to N days).
+      #
+      # @param days [Integer] The maximum number of days to go into the future.
+      # @return [Date]
+      #
+      # @example
+      #   Faker::Date.forward(days: 23) #=> #<Date: 2014-10-03>
+      #
+      # @faker.version 1.0.0
       def forward(legacy_days = NOT_GIVEN, days: 365)
         warn_for_deprecated_arguments do |keywords|
           keywords << :days if legacy_days != NOT_GIVEN
@@ -49,6 +85,16 @@ module Faker
         between(from: from, to: to).to_date
       end
 
+      ##
+      # Produce a random date in the past (up to N days).
+      #
+      # @param days [Integer] The maximum number of days to go into the past.
+      # @return [Date]
+      #
+      # @example
+      #   Faker::Date.backward(days: 14) #=> #<Date: 2019-09-12>
+      #
+      # @faker.version 1.0.0
       def backward(legacy_days = NOT_GIVEN, days: 365)
         warn_for_deprecated_arguments do |keywords|
           keywords << :days if legacy_days != NOT_GIVEN
@@ -60,6 +106,17 @@ module Faker
         between(from: from, to: to).to_date
       end
 
+      ##
+      # Produce a random date in the past (up to N days).
+      #
+      # @param min_age [Integer] The minimum age that the birthday would imply.
+      # @param max_age [Integer] The maximum age that the birthday would imply.
+      # @return [Date]
+      #
+      # @example
+      #   Faker::Date.birthday(min_age: 18, max_age: 65) #=> #<Date: 1986-03-28>
+      #
+      # @faker.version 1.4.3
       def birthday(legacy_min_age = NOT_GIVEN, legacy_max_age = NOT_GIVEN, min_age: 18, max_age: 65)
         warn_for_deprecated_arguments do |keywords|
           keywords << :min_age if legacy_min_age != NOT_GIVEN
@@ -76,6 +133,30 @@ module Faker
         between(from: from, to: to).to_date
       end
 
+      ##
+      # Produces a date in the year and/or month specified.
+      #
+      # @param month [Integer] represents the month of the date
+      # @param year [Integer] represents the year of the date
+      # @return [Date]
+      #
+      # @example
+      #   Faker::Date.in_date_period #=> #<Date: 2019-09-01>
+      #
+      # @example
+      #   Faker::Date.in_date_period(year: 2018, month: 2) #=> #<Date: 2018-02-26>
+      #
+      # @example
+      #   Faker::Date.in_date_period(month: 2) #=> #<Date: 2019-02-26>
+      #
+      # @faker.version next
+      def in_date_period(month: nil, year: ::Date.today.year)
+        from = ::Date.new(year, month || 1, 1)
+        to = ::Date.new(year, month || 12, ::Date.civil(year, month || 12, -1).day)
+
+        between(from: from, to: to).to_date
+      end
+
       private
 
       def birthday_date(date, age)

data/lib/faker/default/demographic.rb

@@ -3,26 +3,83 @@
 module Faker
   class Demographic < Base
     class << self
+      ##
+      # Produces the name of a race.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Demographic.race #=> "Native Hawaiian or Other Pacific Islander"
+      #
+      # @faker.version 1.7.3
       def race
         fetch('demographic.race')
       end
 
+      ##
+      # Produces a level of educational attainment.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Demographic.educational_attainment #=> "GED or alternative credential"
+      #
+      # @faker.version 1.7.3
       def educational_attainment
         fetch('demographic.educational_attainment')
       end
 
+      ##
+      # Produces a denonym.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Demographic.denonym #=> "Panamanian"
+      #
+      # @faker.version 1.7.3
       def demonym
         fetch('demographic.demonym')
       end
 
+      ##
+      # Produces a marital status.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Demographic.marital_status #=> "Widowed"
+      #
+      # @faker.version 1.7.3
       def marital_status
         fetch('demographic.marital_status')
       end
 
+      ##
+      # Produces a sex for demographic purposes.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Demographic.sex #=> "Female"
+      #
+      # @faker.version 1.7.3
       def sex
         fetch('demographic.sex')
       end
 
+      ##
+      # Produces a height as a string.
+      #
+      # @param unit [Symbol] either `:metric` or `imperial`.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Demographic.height #=> "1.61"
+      # @example
+      #   Faker::Demographic.height(unit: :imperial) #=> "6 ft, 2 in"
+      #
+      # @faker.version 1.7.3
       def height(legacy_unit = NOT_GIVEN, unit: :metric)
         warn_for_deprecated_arguments do |keywords|
           keywords << :unit if legacy_unit != NOT_GIVEN

data/lib/faker/default/driving_licence.rb

@@ -52,9 +52,9 @@ module Faker
         year = dob.year % 10
         month = gender == :female ? dob.month + 50 : dob.month
         # Rubocop's preferred formatting is pretty gory
-        # rubocop:disable FormatString
+        # rubocop:disable Style/FormatString
         "#{decade}#{'%02d' % month}#{'%02d' % dob.day}#{year}"
-        # rubocop:enable FormatString
+        # rubocop:enable Style/FormatString
       end
 
       def gb_licence_checksum

data/lib/faker/default/educator.rb

@@ -5,30 +5,84 @@ module Faker
     flexible :educator
 
     class << self
+      ##
+      # Produces a university name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Educator.university #=> "Mallowtown Technical College"
+      #
+      # @faker.version 1.6.4
       def university
-        "#{parse('educator.name')} #{fetch('educator.tertiary.type')}"
+        parse('educator.university')
       end
 
+      ##
+      # Produces a university degree.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Educator.degree #=> "Associate Degree in Criminology"
+      #
+      # @faker.version 1.9.2
       def degree
-        "#{fetch('educator.tertiary.degree.type')} #{fetch('educator.tertiary.degree.subject')}"
+        parse('educator.degree')
       end
 
       alias course degree
 
+      ##
+      # Produces a university subject.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Educator.subject #=> "Criminology"
+      #
+      # @faker.version 1.9.2
       def subject
-        fetch('educator.tertiary.degree.subject')
+        fetch('educator.subject')
       end
 
+      ##
+      # Produces a course name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Educator.course_name #=> "Criminology 101"
+      #
+      # @faker.version 1.9.2
       def course_name
-        "#{fetch('educator.tertiary.degree.subject')} #{numerify(fetch('educator.tertiary.degree.course_number'))}"
+        numerify(parse('educator.course_name'))
       end
 
+      ##
+      # Produces a secondary school.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Educator.secondary_school #=> "Iceborough Secondary College"
+      #
+      # @faker.version 1.6.4
       def secondary_school
-        "#{parse('educator.name')} #{fetch('educator.secondary')}"
+        parse('educator.secondary_school')
       end
 
+      ##
+      # Produces a campus name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Educator.campus #=> "Vertapple Campus"
+      #
+      # @faker.version 1.6.4
       def campus
-        "#{parse('educator.name')} Campus"
+        parse('educator.campus')
       end
     end
   end

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