faker 2.5.0 → 2.9.0

data/lib/faker/default/crypto.rb

@@ -5,14 +5,41 @@ require 'digest'
 module Faker
   class Crypto < Base
     class << self
+      ##
+      # Produces an MD5 hash.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Crypto.md5 #=> "6b5ed240042e8a65c55ddb826c3408e6"
+      #
+      # @faker.version 1.6.4
       def md5
         Digest::MD5.hexdigest(Lorem.characters)
       end
 
+      ##
+      # Produces a SHA1 hash.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Crypto.sha1 #=> "4e99e31c51eef8b2d290e709f757f92e558a503f"
+      #
+      # @faker.version 1.6.4
       def sha1
         Digest::SHA1.hexdigest(Lorem.characters)
       end
 
+      ##
+      # Produces a SHA256 hash.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Crypto.sha256 #=> "51e4dbb424cd9db1ec5fb989514f2a35652ececef33f21c8dd1fd61bb8e3929d"
+      #
+      # @faker.version 1.6.4
       def sha256
         Digest::SHA256.hexdigest(Lorem.characters)
       end

data/lib/faker/default/currency.rb

@@ -3,14 +3,41 @@
 module Faker
   class Currency < Base
     class << self
+      ##
+      # Produces the name of a currency.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Currency.name #=> "Swedish Krona"
+      #
+      # @faker.version 1.9.0
       def name
         fetch('currency.name')
       end
 
+      ##
+      # Produces a currency code.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Currency.code #=> "USD"
+      #
+      # @faker.version 1.9.0
       def code
         fetch('currency.code')
       end
 
+      ##
+      # Produces a currency symbol.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Currency.symbol #=> "$"
+      #
+      # @faker.version 1.9.0
       def symbol
         fetch('currency.symbol')
       end

data/lib/faker/default/date.rb

@@ -133,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