faker 2.3.0 → 2.8.0

data/lib/faker/default/coin.rb

@@ -3,10 +3,28 @@
 module Faker
   class Coin < Base
     class << self
+      ##
+      # Retrieves a random coin from any country.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Coin.name #=> "Brazilian Real"
+      #
+      # @faker.version 1.9.2
       def name
         fetch('currency.name')
       end
 
+      ##
+      # Retrieves a face to a flipped coin
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Coin.flip #=> "Heads"
+      #
+      # @faker.version 1.9.2
       def flip
         fetch('coin.flip')
       end

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/dessert.rb

@@ -5,14 +5,41 @@ module Faker
     flexible :dessert
 
     class << self
+      ##
+      # Produces the name of a dessert variety.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Dessert.variety #=> "Cake"
+      #
+      # @faker.version 1.8.0
       def variety
         fetch('dessert.variety')
       end
 
+      ##
+      # Produces the name of a dessert topping.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Dessert.topping #=> "Gummy Bears"
+      #
+      # @faker.version 1.8.0
       def topping
         fetch('dessert.topping')
       end
 
+      ##
+      # Produces the name of a dessert flavor.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Dessert.flavor #=> "Salted Caramel"
+      #
+      # @faker.version 1.8.0
       def flavor
         fetch('dessert.flavor')
       end

data/lib/faker/default/device.rb

@@ -3,26 +3,80 @@
 module Faker
   class Device < Base
     class << self
+      ##
+      # Produces a build number between 1 and 500.
+      #
+      # @return [Integer]
+      #
+      # @example
+      #   Faker::Device.build_number #=> 5
+      #
+      # @faker.version 1.9.0
       def build_number
         Faker::Number.between(from: 1, to: 500)
       end
 
+      ##
+      # Produces the name of a manufacturer for a device.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Device.manufacturer #=> "Apple"
+      #
+      # @faker.version 1.9.0
       def manufacturer
         fetch('device.manufacturer')
       end
 
+      ##
+      # Produces a model name for a device.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Device.model_name #=> "iPhone 4"
+      #
+      # @faker.version 1.9.0
       def model_name
         fetch('device.model_name')
       end
 
+      ##
+      # Produces the name of a platform for a device.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Device.platform #=> "webOS"
+      #
+      # @faker.version 1.9.0
       def platform
         fetch('device.platform')
       end
 
+      ##
+      # Produces a serial code for a device.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Device.serial #=> "ejfjnRNInxh0363JC2WM"
+      #
+      # @faker.version 1.9.0
       def serial
         fetch('device.serial')
       end
 
+      ##
+      # Produces a version number between 1 and 1000.
+      #
+      # @return [Integer]
+      #
+      # @example
+      #   Faker::Device.version #=> 42
+      #
+      # @faker.version 1.9.0
       def version
         Faker::Number.between(from: 1, to: 1000)
       end

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/electrical_components.rb

@@ -5,14 +5,41 @@ module Faker
     flexible :electrical_components
 
     class << self
+      ##
+      # Produces an active electrical component.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::ElectricalComponents.active #=> "Transistor"
+      #
+      # @faker.version 1.9.0
       def active
         fetch('electrical_components.active')
       end
 
+      ##
+      # Produces a passive electrical component.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::ElectricalComponents.passive #=> "Resistor"
+      #
+      # @faker.version 1.9.0
       def passive
         fetch('electrical_components.passive')
       end
 
+      ##
+      # Produces an electromechanical electrical component.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::ElectricalComponents.electromechanical #=> "Toggle Switch"
+      #
+      # @faker.version 1.9.0
       def electromechanical
         fetch('electrical_components.electromechanical')
       end

data/lib/faker/default/greek_philosophers.rb

@@ -3,10 +3,28 @@
 module Faker
   class GreekPhilosophers < Base
     class << self
+      ##
+      # Produces the name of a Greek philosopher.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::GreekPhilosophers.name #=> "Socrates"
+      #
+      # @faker.version 1.9.0
       def name
         fetch('greek_philosophers.names')
       end
 
+      ##
+      # Produces a quote from a Greek philosopher.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::GreekPhilosophers.quote #=> "Only the educated are free."
+      #
+      # @faker.version 1.9.0
       def quote
         fetch('greek_philosophers.quotes')
       end

data/lib/faker/default/id_number.rb

@@ -16,6 +16,8 @@ module Faker
     BRAZILIAN_ID_FROM = 10_000_000
     BRAZILIAN_ID_TO = 99_999_999
 
+    CHILEAN_MODULO = 11
+
     class << self
       def valid
         _translate('valid')
@@ -105,8 +107,35 @@ module Faker
 
       alias brazilian_rg brazilian_id
 
+      def chilean_id
+        digits = Faker::Number.number(digits: 8)
+        verification_code = chilean_verification_code(digits)
+
+        digits.to_s + '-' + verification_code.to_s
+      end
+
       private
 
+      def chilean_verification_code(digits)
+        # First digit is multiplied by 3, second by 2, and so on
+        multiplication_rule = [3, 2, 7, 6, 5, 4, 3, 2]
+        digits_splitted = digits.to_s.chars.map(&:to_i)
+
+        sum = digits_splitted.map.with_index { |digit, index| digit * multiplication_rule[index] }.reduce(:+)
+
+        modulo = sum.modulo(CHILEAN_MODULO)
+        difference = CHILEAN_MODULO - modulo
+
+        case difference
+        when 0..9
+          difference
+        when 10
+          'K'
+        when 11
+          0
+        end
+      end
+
       def south_african_id_checksum_digit(id_number)
         value_parts = id_number.chars
         even_digits = value_parts

data/lib/faker/default/industry_segments.rb

@@ -5,18 +5,54 @@ module Faker
     flexible :industry_segments
 
     class << self
+      ##
+      # Produces the name of an industry.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::IndustrySegments.industry #=> "Basic Materials"
+      #
+      # @faker.version 1.9.2
       def industry
         fetch('industry_segments.industry')
       end
 
+      ##
+      # Produces the name of a super-sector of an industry.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::IndustrySegments.super_sector #=> "Basic Resources"
+      #
+      # @faker.version 1.9.2
       def super_sector
         fetch('industry_segments.super_sector')
       end
 
+      ##
+      # Produces the name of a sector of an industry.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::IndustrySegments.sector #=> "Industrial Metals & Mining"
+      #
+      # @faker.version 1.9.2
       def sector
         fetch('industry_segments.sector')
       end
 
+      ##
+      # Produces the name of a subsector of an industry.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::IndustrySegments.industry #=> "Basic Materials"
+      #
+      # @faker.version 1.9.2
       def sub_sector
         fetch('industry_segments.sub_sector')
       end