faker 2.8.0 → 2.10.2

data/lib/faker/default/ancient.rb

@@ -3,18 +3,54 @@
 module Faker
   class Ancient < Base
     class << self
+      ##
+      # Produces a god from ancient mythology.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Ancient.god #=> "Zeus"
+      #
+      # @faker.version 1.7.0
       def god
         fetch('ancient.god')
       end
 
+      ##
+      # Produces a primordial from ancient mythology.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Ancient.primordial #=> "Gaia"
+      #
+      # @faker.version 1.7.0
       def primordial
         fetch('ancient.primordial')
       end
 
+      ##
+      # Produces a titan from ancient mythology.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Ancient.titan #=> "Atlas"
+      #
+      # @faker.version 1.7.0
       def titan
         fetch('ancient.titan')
       end
 
+      ##
+      # Produces a hero from ancient mythology.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Ancient.hero #=> "Achilles"
+      #
+      # @faker.version 1.7.0
       def hero
         fetch('ancient.hero')
       end

data/lib/faker/default/bank.rb

@@ -18,7 +18,7 @@ module Faker
       end
 
       def iban(legacy_country_code = NOT_GIVEN, country_code: 'GB')
-        # Each country has it's own format for bank accounts
+        # Each country has its own format for bank accounts
         # Many of them use letters in certain parts of the account
         # Using regex patterns we can create virtually any type of bank account
         warn_for_deprecated_arguments do |keywords|

data/lib/faker/default/beer.rb

@@ -5,34 +5,106 @@ module Faker
     flexible :beer
 
     class << self
+      ##
+      # Produces a random beer name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Beer.name #=> "Pliny The Elder"
+      #
+      # @faker.version 1.6.2
       def name
         fetch('beer.name')
       end
 
+      ##
+      # Produces a random beer style.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Beer.style #=> "Wood-aged Beer"
+      #
+      # @faker.version 1.6.2
       def style
         fetch('beer.style')
       end
 
+      ##
+      # Produces a random beer hops.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Beer.hop #=> "Sterling"
+      #
+      # @faker.version 1.6.2
       def hop
         fetch('beer.hop')
       end
 
+      ##
+      # Produces a random beer yeast.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Beer.yeast #=> "5335 - Lactobacillus"
+      #
+      # @faker.version 1.6.2
       def yeast
         fetch('beer.yeast')
       end
 
+      ##
+      # Produces a random beer malt.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Beer.malts #=> "Munich"
+      #
+      # @faker.version 1.6.2
       def malts
         fetch('beer.malt')
       end
 
+      ##
+      # Produces a random beer IBU.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Beer.ibu #=> "87 IBU"
+      #
+      # @faker.version 1.6.2
       def ibu
         rand(10..100).to_s + ' IBU'
       end
 
+      ##
+      # Produces a random beer alcohol percentage.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Beer.alcohol #=> "5.4%"
+      #
+      # @faker.version 1.6.2
       def alcohol
         rand(2.0..10.0).round(1).to_s + '%'
       end
 
+      ##
+      # Produces a random beer blg level.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Beer.blg #=> "5.1Blg"
+      #
+      # @faker.version 1.6.2
       def blg
         rand(5.0..20.0).round(1).to_s + '°Blg'
       end

data/lib/faker/default/bossa_nova.rb

@@ -3,10 +3,28 @@
 module Faker
   class BossaNova < Base
     class << self
+      ##
+      # Produces the name of a bossa nova artist.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::BossaNova.artist #=> "Tom Jobin"
+      #
+      # @faker.version 1.8.3
       def artist
         fetch('bossa_nova.artists')
       end
 
+      ##
+      # Produces a bossa nova song.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::BossaNova.song #=> "Chega de Saudade"
+      #
+      # @faker.version 1.8.3
       def song
         fetch('bossa_nova.songs')
       end

data/lib/faker/default/business.rb

@@ -7,14 +7,41 @@ module Faker
     flexible :business
 
     class << self
+      ##
+      # Produces a credit card number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Business.credit_card_number #=> "1228-1221-1221-1431"
+      #
+      # @faker.version 1.2.0
       def credit_card_number
         fetch('business.credit_card_numbers')
       end
 
+      ##
+      # Produces a credit card expiration date.
+      #
+      # @return [Date]
+      #
+      # @example
+      #   Faker::Business.credit_card_number #=> <Date: 2015-11-11 ((2457338j,0s,0n),+0s,2299161j)>
+      #
+      # @faker.version 1.2.0
       def credit_card_expiry_date
         ::Date.today + (365 * rand(1..4))
       end
 
+      ##
+      # Produces a type of credit card.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Business.credit_card_type #=> "visa"
+      #
+      # @faker.version 1.2.0
       def credit_card_type
         fetch('business.credit_card_types')
       end

data/lib/faker/default/chuck_norris.rb

@@ -5,7 +5,17 @@ module Faker
     flexible :chuck_norris
 
     class << self
-      # from: https://github.com/jenkinsci/chucknorris-plugin/blob/master/src/main/java/hudson/plugins/chucknorris/FactGenerator.java
+      # Produces a Chuck Norris Fact.
+      # Original list of facts:
+      # https://github.com/jenkinsci/chucknorris-plugin/blob/master/src/main/java/hudson/plugins/chucknorris/FactGenerator.java
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::ChuckNorris.fact
+      #     #=> "Chuck Norris can solve the Towers of Hanoi in one move."
+      #
+      # @faker.version 1.6.4
       def fact
         fetch('chuck_norris.fact')
       end

data/lib/faker/default/color.rb

@@ -3,27 +3,74 @@
 module Faker
   class Color < Base
     class << self
+      ##
+      # Produces a hex color code.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Color.hex_color #=> "#31a785"
+      #
+      # @faker.version 1.5.0
       def hex_color
         format('#%06x', (rand * 0xffffff))
       end
 
+      ##
+      # Produces the name of a color.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Color.color_name #=> "yellow"
+      #
+      # @faker.version 1.6.2
       def color_name
         fetch('color.name')
       end
 
+      # @private
       def single_rgb_color
         sample((0..255).to_a)
       end
 
+      ##
+      # Produces an array of integers representing an RGB color.
+      #
+      # @return [Array(Integer, Integer, Integer)]
+      #
+      # @example
+      #   Faker::Color.rgb_color #=> [54, 233, 67]
+      #
+      # @faker.version 1.5.0
       def rgb_color
         Array.new(3) { single_rgb_color }
       end
 
-      # returns [hue, saturation, lightness]
+      ##
+      # Produces an array of floats representing an HSL color.
+      # The array is in the form of `[hue, saturation, lightness]`.
+      #
+      # @return [Array(Float, Float, Float)]
+      #
+      # @example
+      #   Faker::Color.hsl_color #=> [69.87, 0.66, 0.3]
+      #
+      # @faker.version 1.5.0
       def hsl_color
         [sample((0..360).to_a), rand.round(2), rand.round(2)]
       end
 
+      ##
+      # Produces an array of floats representing an HSLA color.
+      # The array is in the form of `[hue, saturation, lightness, alpha]`.
+      #
+      # @return [Array(Float, Float, Float, Float)]
+      #
+      # @example
+      #   Faker::Color.hsla_color #=> [154.77, 0.36, 0.9, 0.2]
+      #
+      # @faker.version 1.5.0
       def hsla_color
         hsl_color << rand.round(1)
       end

data/lib/faker/default/company.rb

@@ -5,57 +5,163 @@ module Faker
     flexible :company
 
     class << self
+      ##
+      # Produces a company name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.name #=> "Roberts Inc"
+      #
+      # @faker.version 1.6.0
       def name
         parse('company.name')
       end
 
+      ##
+      # Produces a company suffix.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.suffix #=> "LLC"
+      #
+      # @faker.version 1.6.0
       def suffix
         fetch('company.suffix')
       end
 
+      ##
+      # Produces a company industry.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.industry #=> "Food & Beverages"
+      #
+      # @faker.version 1.6.0
       def industry
         fetch('company.industry')
       end
 
-      # Generate a buzzword-laden catch phrase.
+      ##
+      # Produces a company catch phrase.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.catch_phrase #=> "Grass-roots grid-enabled portal"
+      #
+      # @faker.version 1.6.0
       def catch_phrase
         translate('faker.company.buzzwords').collect { |list| sample(list) }.join(' ')
       end
 
+      ##
+      # Produces a company buzzword.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.buzzword #=> "flexibility"
+      #
+      # @faker.version 1.8.7
       def buzzword
         sample(translate('faker.company.buzzwords').flatten)
       end
 
+      ##
+      # Produces some company BS.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.bs #=> "empower customized functionalities"
+      #
+      # @faker.version 1.6.0
       # When a straight answer won't do, BS to the rescue!
       def bs
         translate('faker.company.bs').collect { |list| sample(list) }.join(' ')
       end
 
+      ##
+      # Produces a company EIN (Employer Identification Number).
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.ein #=> "07-4009024"
+      #
+      # @faker.version 1.6.0
       def ein
         format('%09d', rand(10**9)).gsub(/(\d{2})(\d{7})/, '\\1-\\2')
       end
 
+      ##
+      # Produces a company duns number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.duns_number #=> "70-655-5105"
+      #
+      # @faker.version 1.6.0
       def duns_number
         format('%09d', rand(10**9)).gsub(/(\d{2})(\d{3})(\d{4})/, '\\1-\\2-\\3')
       end
 
+      ##
+      # Produces a company logo.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.logo #=> "https://pigment.github.io/fake-logos/logos/medium/color/12.png"
+      #
+      # @faker.version 1.8.7
       # Get a random company logo url in PNG format.
       def logo
         rand_num = rand(1..13)
         "https://pigment.github.io/fake-logos/logos/medium/color/#{rand_num}.png"
       end
 
+      ##
+      # Produces a company type.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.type #=> "Partnership"
+      #
+      # @faker.version 1.8.7
       def type
         fetch('company.type')
       end
 
+      ##
+      # Produces a company profession.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.profession #=> "factory worker"
+      #
+      # @faker.version 1.6.0
       def profession
         fetch('company.profession')
       end
 
-      # rubocop:disable Style/AsciiComments
-      # Get a random Spanish organization number. See more here https://es.wikipedia.org/wiki/Número_de_identificación_fiscal
-      # rubocop:enable Style/AsciiComments
+      ##
+      # Produces a company spanish organisation number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.spanish_organisation_number #=> "D6819358"
+      #
+      # @faker.version 1.8.5
+      #
+      # Get a random Spanish organization number. See more here https://es.wikipedia.org/wiki/N%C3%BAmero_de_identificaci%C3%B3n_fiscal
       def spanish_organisation_number
         # Valid leading character: A, B, C, D, E, F, G, H, J, N, P, Q, R, S, U, V, W
         # 7 digit numbers
@@ -64,6 +170,15 @@ module Faker
         base
       end
 
+      ##
+      # Produces a company swedish organisation number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.swedish_organisation_number #=> "3866029808"
+      #
+      # @faker.version 1.7.0
       # Get a random Swedish organization number. See more here https://sv.wikipedia.org/wiki/Organisationsnummer
       def swedish_organisation_number
         # Valid leading digit: 1, 2, 3, 5, 6, 7, 8, 9
@@ -73,6 +188,15 @@ module Faker
         base + luhn_algorithm(base).to_s
       end
 
+      ##
+      # Produces a company czech organisation number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.czech_organisation_number #=> "90642741"
+      #
+      # @faker.version 1.9.1
       def czech_organisation_number
         sum = 0
         base = []
@@ -84,18 +208,45 @@ module Faker
         base.join
       end
 
+      ##
+      # Produces a company french siren number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.french_siren_number #=> "163417827"
+      #
+      # @faker.version 1.8.5
       # Get a random French SIREN number. See more here https://fr.wikipedia.org/wiki/Syst%C3%A8me_d%27identification_du_r%C3%A9pertoire_des_entreprises
       def french_siren_number
         base = (1..8).map { rand(10) }.join
         base + luhn_algorithm(base).to_s
       end
 
+      ##
+      # Produces a company french siret number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.french_siret_number #=> "76430067900496"
+      #
+      # @faker.version 1.8.5
       def french_siret_number
         location = rand(100).to_s.rjust(4, '0')
         org_no = french_siren_number + location
         org_no + luhn_algorithm(org_no).to_s
       end
 
+      ##
+      # Produces a company norwegian organisation number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.norwegian_organisation_number #=> "842457173"
+      #
+      # @faker.version 1.8.0
       # Get a random Norwegian organization number. Info: https://www.brreg.no/om-oss/samfunnsoppdraget-vart/registera-vare/einingsregisteret/organisasjonsnummeret/
       def norwegian_organisation_number
         # Valid leading digit: 8, 9
@@ -107,6 +258,15 @@ module Faker
         base + mod11_check.to_s
       end
 
+      ##
+      # Produces a company australian business number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.australian_business_number #=> "93579396170"
+      #
+      # @faker.version 1.6.4
       def australian_business_number
         base = format('%09d', rand(10**9))
         abn = "00#{base}"
@@ -114,6 +274,15 @@ module Faker
         (99 - (abn_checksum(abn) % 89)).to_s + base
       end
 
+      ##
+      # Produces a company polish taxpayer identification_number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.polish_taxpayer_identification_number #=> "2767549463"
+      #
+      # @faker.version 1.9.1
       # Get a random Polish taxpayer identification number More info https://pl.wikipedia.org/wiki/NIP
       def polish_taxpayer_identification_number
         result = []
@@ -125,6 +294,15 @@ module Faker
         result.join('')
       end
 
+      ##
+      # Produces a company polish register of national economy.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.polish_register_of_national_economy #=> "788435970"
+      #
+      # @faker.version 1.9.1
       # Get a random Polish register of national economy number. More info https://pl.wikipedia.org/wiki/REGON
       def polish_register_of_national_economy(legacy_length = NOT_GIVEN, length: 9)
         warn_for_deprecated_arguments do |keywords|
@@ -141,22 +319,67 @@ module Faker
         random_digits.join('')
       end
 
+      ##
+      # Produces a company south african pty ltd registration number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.south_african_pty_ltd_registration_number #=> "7043/2400717902/07"
+      #
+      # @faker.version 1.9.2
       def south_african_pty_ltd_registration_number
         regexify(/\d{4}\/\d{4,10}\/07/)
       end
 
+      ##
+      # Produces a company south african close corporation registration number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.south_african_close_corporation_registration_number #=> "CK38/5739937418/23"
+      #
+      # @faker.version 1.9.2
       def south_african_close_corporation_registration_number
         regexify(/(CK\d{2}|\d{4})\/\d{4,10}\/23/)
       end
 
+      ##
+      # Produces a company south african listed company registration number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.south_african_listed_company_registration_number #=> "2512/87676/06"
+      #
+      # @faker.version 1.9.2
       def south_african_listed_company_registration_number
         regexify(/\d{4}\/\d{4,10}\/06/)
       end
 
+      ##
+      # Produces a company south african trust registration number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.south_african_trust_registration_number #=> "IT5673/937519896"
+      #
+      # @faker.version 1.9.2
       def south_african_trust_registration_number
         regexify(/IT\d{2,4}\/\d{2,10}/)
       end
 
+      ##
+      # Produces a company brazilian company number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.brazilian_company_number #=> "37205322000500"
+      #
+      # @faker.version 1.9.2
       def brazilian_company_number(legacy_formatted = NOT_GIVEN, formatted: false)
         warn_for_deprecated_arguments do |keywords|
           keywords << :formatted if legacy_formatted != NOT_GIVEN
@@ -176,6 +399,15 @@ module Faker
         formatted ? format('%s.%s.%s/%s-%s', *number.scan(/(\d{2})(\d{3})(\d{3})(\d{4})(\d{2})/).flatten) : number
       end
 
+      ##
+      # Produces a company sic code.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.sic_code #=> "7383"
+      #
+      # @faker.version 1.9.4
       def sic_code
         fetch('company.sic_code')
       end