faker 2.3.0 → 2.6.0

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/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

data/lib/faker/default/internet.rb

@@ -73,6 +73,8 @@ module Faker
         end
       end
 
+      # rubocop:disable Metrics/ParameterLists
+
       ##
       # Produces a randomized string of characters suitable for passwords
       #
@@ -95,8 +97,8 @@ module Faker
       #   Faker::Internet.password(min_length: 10, max_length: 20, mix_case: true, special_characters: true) #=> "*%NkOnJsH4"
       #
       # @faker.version 2.1.3
-      # rubocop:disable Metrics/ParameterLists
       def password(legacy_min_length = NOT_GIVEN, legacy_max_length = NOT_GIVEN, legacy_mix_case = NOT_GIVEN, legacy_special_characters = NOT_GIVEN, min_length: 8, max_length: 16, mix_case: true, special_characters: false)
+        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :min_length if legacy_min_length != NOT_GIVEN
           keywords << :max_length if legacy_max_length != NOT_GIVEN
@@ -239,6 +241,7 @@ module Faker
         "#{ip_v6_address}/#{rand(1..127)}"
       end
 
+      # rubocop:disable Metrics/ParameterLists
       def url(legacy_host = NOT_GIVEN, legacy_path = NOT_GIVEN, legacy_scheme = NOT_GIVEN, host: domain_name, path: "/#{username}", scheme: 'http')
         # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|

data/lib/faker/default/marketing.rb

@@ -5,6 +5,15 @@ module Faker
     flexible :marketing
 
     class << self
+      ##
+      # Produces the name of a video game console or platform.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Marketing.buzzwords #=> "rubber meets the road"
+      #
+      # @faker.version 1.9.4
       def buzzwords
         fetch('marketing.buzzwords')
       end

data/lib/faker/default/military.rb

@@ -3,22 +3,67 @@
 module Faker
   class Military < Base
     class << self
+      ##
+      # Produces a rank in the U.S. Army.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Military.army_rank #=> "Staff Sergeant"
+      #
+      # @faker.version 1.9.0
       def army_rank
         fetch('military.army_rank')
       end
 
+      ##
+      # Produces a rank in the U.S. Marines.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Military.marines_rank #=> "Gunnery Sergeant"
+      #
+      # @faker.version 1.9.0
       def marines_rank
         fetch('military.marines_rank')
       end
 
+      ##
+      # Produces a rank in the U.S. Navy.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Military.navy_rank #=> "Seaman"
+      #
+      # @faker.version 1.9.0
       def navy_rank
         fetch('military.navy_rank')
       end
 
+      ##
+      # Produces a rank in the U.S. Air Force.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Military.air_force_rank #=> "Captain"
+      #
+      # @faker.version 1.9.0
       def air_force_rank
         fetch('military.air_force_rank')
       end
 
+      ##
+      # Produces a U.S. Department of Defense Paygrade.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Military.dod_paygrade #=> "E-6"
+      #
+      # @faker.version 1.9.0
       def dod_paygrade
         fetch('military.dod_paygrade')
       end

data/lib/faker/default/nation.rb

@@ -4,27 +4,70 @@ module Faker
   class Nation < Base
     flexible :nation
     class << self
-      # Fetch random nationality
+      ##
+      # Produces a random nationality.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Nation.nationality #=> "Nepalese"
+      #
+      # @faker.version 1.9.0
       def nationality
         fetch('nation.nationality')
       end
 
-      # Fetch random national flag emoji
+      # rubocop:disable Style/AsciiComments
+
+      ##
+      # Produces a random national flag emoji.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Nation.flag #=> "🇫🇮"
+      #
+      # @faker.version 1.9.0
       def flag
         sample(translate('faker.nation.flag')).pack('C*').force_encoding('utf-8')
       end
+      # rubocop:enable Style/AsciiComments
 
-      # Fetch random language
+      ##
+      # Produces a random national language.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Nation.language #=> "Nepali"
+      #
+      # @faker.version 1.9.0
       def language
         fetch('nation.language')
       end
 
-      # Fetch random capital city
+      ##
+      # Produces a random capital city.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Nation.capital_city #=> "Kathmandu"
+      #
+      # @faker.version 1.9.0
       def capital_city
         fetch('nation.capital_city')
       end
 
-      # Fetch random natinal sport
+      ##
+      # Produces a random national sport.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Nation.national_sport #=> "dandi biyo"
+      #
+      # @faker.version 1.9.0
       def national_sport
         fetch('team.sport')
       end

data/lib/faker/default/nato_phonetic_alphabet.rb

@@ -3,6 +3,15 @@
 module Faker
   class NatoPhoneticAlphabet < Base
     class << self
+      ##
+      # Produces a code word from the NATO phonetic alphabet.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::NatoPhoneticAlphabet.code_word #=> "Hotel"
+      #
+      # @faker.version 1.9.0
       def code_word
         fetch('nato_phonetic_alphabet.code_word')
       end

data/lib/faker/default/number.rb

@@ -3,6 +3,16 @@
 module Faker
   class Number < Base
     class << self
+      ##
+      # Produce a random number.
+      #
+      # @param digits [Integer] Number of digits that the generated number should have.
+      # @return [Integer]
+      #
+      # @example
+      #   Faker::Number.number(digits: 10) #=> 1968353479
+      #
+      # @faker.version 1.0.0
       def number(legacy_digits = NOT_GIVEN, digits: 10)
         warn_for_deprecated_arguments do |keywords|
           keywords << :digits if legacy_digits != NOT_GIVEN
@@ -15,6 +25,16 @@ module Faker
         ([non_zero_digit] + generate(digits - 1)).join.to_i
       end
 
+      ##
+      # Produce a random number with a leading zero.
+      #
+      # @param digits [Integer] Number of digits that the generated number should have.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Number.leading_zero_number(digits: 10) #=> "0669336915"
+      #
+      # @faker.version 1.0.0
       def leading_zero_number(legacy_digits = NOT_GIVEN, digits: 10)
         warn_for_deprecated_arguments do |keywords|
           keywords << :digits if legacy_digits != NOT_GIVEN
@@ -23,6 +43,16 @@ module Faker
         '0' + (2..digits).collect { digit }.join
       end
 
+      ##
+      # Produce a number with a number of digits, preserves leading zeroes.
+      #
+      # @param digits [Integer] Number of digits that the generated number should have.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Number.decimal_part(digits: 2) #=> "09"
+      #
+      # @faker.version 1.0.0
       def decimal_part(legacy_digits = NOT_GIVEN, digits: 10)
         warn_for_deprecated_arguments do |keywords|
           keywords << :digits if legacy_digits != NOT_GIVEN
@@ -36,6 +66,18 @@ module Faker
         leading_zero_number(digits: digits) + num.to_s
       end
 
+      ##
+      # Produces a float.
+      #
+      # @param l_digits [Integer] Number of digits that the generated decimal should have to the left of the decimal point.
+      # @param r_digits [Integer] Number of digits that the generated decimal should have to the right of the decimal point.
+      # @return [Float]
+      #
+      # @example
+      #   Faker::Number.decimal(l_digits: 2) #=> 11.88
+      #   Faker::Number.decimal(l_digits: 3, r_digits: 3) #=> 181.843
+      #
+      # @faker.version 1.0.0
       def decimal(legacy_l_digits = NOT_GIVEN, legacy_r_digits = NOT_GIVEN, l_digits: 5, r_digits: 2)
         warn_for_deprecated_arguments do |keywords|
           keywords << :l_digits if legacy_l_digits != NOT_GIVEN
@@ -53,14 +95,42 @@ module Faker
         "#{l_d}.#{r_d}".to_f
       end
 
+      ##
+      # Produces a non-zero single-digit integer.
+      #
+      # @return [Integer]
+      #
+      # @example
+      #   Faker::Number.non_zero_digit #=> 8
+      #
+      # @faker.version 1.0.0
       def non_zero_digit
         rand(1..9)
       end
 
+      ##
+      # Produces a single-digit integer.
+      #
+      # @return [Integer]
+      #
+      # @example
+      #   Faker::Number.digit #=> 1
+      #
+      # @faker.version 1.0.0
       def digit
         rand(10)
       end
 
+      ##
+      # Produces a number in hexadecimal format.
+      #
+      # @param digits [Integer] Number of digits in the he
+      # @return [String]
+      #
+      # @example
+      #   Faker::Number.hexadecimal(digits: 3) #=> "e74"
+      #
+      # @faker.version 1.0.0
       def hexadecimal(legacy_digits = NOT_GIVEN, digits: 6)
         warn_for_deprecated_arguments do |keywords|
           keywords << :digits if legacy_digits != NOT_GIVEN
@@ -71,6 +141,17 @@ module Faker
         hex
       end
 
+      ##
+      # Produces a float given a mean and standard deviation.
+      #
+      # @param mean [Integer]
+      # @param standard_deviation [Integer, Float]
+      # @return [Float]
+      #
+      # @example
+      #   Faker::Number.normal(mean: 50, standard_deviation: 3.5) #=> 47.14669604069156
+      #
+      # @faker.version 1.0.0
       def normal(legacy_mean = NOT_GIVEN, legacy_standard_deviation = NOT_GIVEN, mean: 1, standard_deviation: 1)
         warn_for_deprecated_arguments do |keywords|
           keywords << :mean if legacy_mean != NOT_GIVEN
@@ -83,6 +164,17 @@ module Faker
         mean + scale * Math.cos(theta)
       end
 
+      ##
+      # Produces a number between two provided values. Boundaries are inclusive.
+      #
+      # @param from [Integer] The lowest number to include.
+      # @param to [Integer] The highest number to include.
+      # @return [Integer]
+      #
+      # @example
+      #   Faker::Number.between(from: 1, to: 10) #=> 7
+      #
+      # @faker.version 1.0.0
       def between(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from: 1.00, to: 5000.00)
         warn_for_deprecated_arguments do |keywords|
           keywords << :from if legacy_from != NOT_GIVEN
@@ -92,6 +184,16 @@ module Faker
         Faker::Base.rand_in_range(from, to)
       end
 
+      ##
+      # Produces a number within two provided values. Boundaries are inclusive or exclusive depending on the range passed.
+      #
+      # @param range [Range] The range from which to generate a number.
+      # @return [Integer]
+      #
+      # @example
+      #   Faker::Number.within(range: 1..10) #=> 7
+      #
+      # @faker.version 1.0.0
       def within(legacy_range = NOT_GIVEN, range: 1.00..5000.00)
         warn_for_deprecated_arguments do |keywords|
           keywords << :range if legacy_range != NOT_GIVEN
@@ -100,6 +202,17 @@ module Faker
         between(from: range.min, to: range.max)
       end
 
+      ##
+      # Produces a positive float.
+      #
+      # @param from [Integer] The lower boundary.
+      # @param to [Integer] The higher boundary.
+      # @return [Float]
+      #
+      # @example
+      #   Faker::Number.positive #=> 235.59238499107653
+      #
+      # @faker.version 1.0.0
       def positive(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from: 1.00, to: 5000.00)
         warn_for_deprecated_arguments do |keywords|
           keywords << :from if legacy_from != NOT_GIVEN
@@ -111,6 +224,17 @@ module Faker
         greater_than_zero(random_number)
       end
 
+      ##
+      # Produces a negative float.
+      #
+      # @param from [Integer] The lower boundary.
+      # @param to [Integer] The higher boundary.
+      # @return [Float]
+      #
+      # @example
+      #   Faker::Number.negative #=> -4480.042585669558
+      #
+      # @faker.version 1.0.0
       def negative(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from: -5000.00, to: -1.00)
         warn_for_deprecated_arguments do |keywords|
           keywords << :from if legacy_from != NOT_GIVEN