faker 2.11.0 → 2.12.0

data/lib/faker/default/south_africa.rb

@@ -3,46 +3,136 @@
 module Faker
   class SouthAfrica < Base
     class << self
+      ##
+      # Produces a South African ID number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SouthAfrica.id_number #=> "6110311856083"
+      #
+      # @faker.version 1.9.2
       def id_number
         Faker::IDNumber.south_african_id_number
       end
 
+      ##
+      # Produces a valid South African ID number
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SouthAfrica.valid_id_number #=> "6110311856083"
+      #
+      # @faker.version 1.9.2
       def valid_id_number
         Faker::IDNumber.valid_south_african_id_number
       end
 
+      ##
+      # Produces an invalid South African ID number
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SouthAfrica.invalid_id_number #=> "7018356904081"
+      #
+      # @faker.version 1.9.2
       def invalid_id_number
         Faker::IDNumber.invalid_south_african_id_number
       end
 
+      ##
+      # Produces a South African phone number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SouthAfrica.phone_number #=> "010 788 5009"
+      #
+      # @faker.version 1.9.2
       def phone_number
         with_locale 'en-ZA' do
           Faker::PhoneNumber.phone_number
         end
       end
 
+      ##
+      # Produces a South African cell phone number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SouthAfrica.cell_phone #=> "082 946 7470"
+      #
+      # @faker.version 1.9.2
       def cell_phone
         with_locale 'en-ZA' do
           Faker::PhoneNumber.cell_phone
         end
       end
 
+      ##
+      # Produces a South African private company registration number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SouthAfrica.pty_ltd_registration_number #=> "5301/714689/07"
+      #
+      # @faker.version 1.9.2
       def pty_ltd_registration_number
         Faker::Company.south_african_pty_ltd_registration_number
       end
 
+      ##
+      # Produces a South African close corporation registration number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SouthAfrica.close_corporation_registration_number #=> "CK74/7585/23"
+      #
+      # @faker.version 1.9.2
       def close_corporation_registration_number
         Faker::Company.south_african_close_corporation_registration_number
       end
 
+      ##
+      # Produces a South African listed company registration number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SouthAfrica.listed_company_registration_number #=> "7039/3135/06"
+      #
+      # @faker.version 1.9.2
       def listed_company_registration_number
         Faker::Company.south_african_listed_company_registration_number
       end
 
+      ##
+      # Produces a South African trust registration number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SouthAfrica.trust_registration_number #=> "IT38/6489900"
+      #
+      # @faker.version 1.9.2
       def trust_registration_number
         Faker::Company.south_african_trust_registration_number
       end
 
+      ##
+      # Produces a South African VAT number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SouthAfrica.vat_number #=> "ZA79494416181"
+      #
+      # @faker.version 1.9.2
       def vat_number
         Faker::Finance.vat_number(country: 'ZA')
       end

data/lib/faker/default/string.rb

@@ -3,6 +3,22 @@
 module Faker
   class String < Base
     class << self
+      ##
+      # Produces a random UTF-8 string with optional nested length selectors.
+      #
+      # @param length [Integer, Range, Array<Integer, Range, nil>] The length of produced string and/or specific UTF-8 characters to use.
+      # @return [String]
+      #
+      # @example
+      #   rubocop:disable Style/AsciiComments
+      #   Faker::String.random #=> "3 뇦\u0017&y\u{3A109}$8^4* 녹豿4좘툢ꔾ쉙6ɉ\uA6 8TN畀챵|\"3쇤Ŵ"
+      #   Faker::String.random(length: 4) #=> "⼨%0*"
+      #   Faker::String.random(length: 3..12) #=> "\u{69FDC};秨툫"
+      #   Faker::String.random(length: [0, 6]) #=> "I轤𣴒P溟L"
+      #   Faker::String.random(length: [1, (2..5), [3, 6], nil]) #=> "葓L#ћ"
+      #   rubocop:enable Style/AsciiComments
+      #
+      # @faker.version 1.9.0
       def random(legacy_length = NOT_GIVEN, length: 32)
         warn_for_deprecated_arguments do |keywords|
           keywords << :length if legacy_length != NOT_GIVEN
@@ -38,9 +54,9 @@ module Faker
 
       def utf8character
         sample([
-                 rand(32..90), # latin alphabet
-                 rand(128),             # 7-bit ASCII
-                 rand(0xd800),          # utf-8 codepoints below utf-16 surrogate halves
+                 rand(32..90),           # latin alphabet
+                 rand(128),              # 7-bit ASCII
+                 rand(0xd800),           # utf-8 codepoints below utf-16 surrogate halves
                  rand(57_344..1_114_111) # utf-8 codepoints above utf-16 surrogate halves
                ]).chr(Encoding::UTF_8)
       end

data/lib/faker/default/stripe.rb

@@ -3,6 +3,17 @@
 module Faker
   class Stripe < Base
     class << self
+      ##
+      # Produces a random valid card number.
+      #
+      # @param card_type [String] Specific valid card type.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Stripe.valid_card #=> "4242424242424242"
+      #   Faker::Stripe.valid_card(card_type: "visa_debit") #=> "4000056655665556"
+      #
+      # @faker.version 1.9.0
       def valid_card(legacy_card_type = NOT_GIVEN, card_type: nil)
         warn_for_deprecated_arguments do |keywords|
           keywords << :card_type if legacy_card_type != NOT_GIVEN
@@ -22,6 +33,17 @@ module Faker
         fetch('stripe.valid_cards.' + card_type)
       end
 
+      ##
+      # Produces a random valid Stripe token.
+      #
+      # @param card_type [String] Specific valid card type.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Stripe.valid_token #=> "tok_visa"
+      #   Faker::Stripe.valid_token(card_type: "mc_debit") #=> "tok_mastercard_debit"
+      #
+      # @faker.version 1.9.0
       def valid_token(legacy_card_type = NOT_GIVEN, card_type: nil)
         warn_for_deprecated_arguments do |keywords|
           keywords << :card_type if legacy_card_type != NOT_GIVEN
@@ -41,6 +63,16 @@ module Faker
         fetch('stripe.valid_tokens.' + card_type)
       end
 
+      ##
+      # Produces a random invalid card number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Stripe.invalid_card #=> "4000000000000002"
+      #   Faker::Stripe.invalid_card(card_error: "addressZipFail") #=> "4000000000000010"
+      #
+      # @faker.version 1.9.0
       def invalid_card(legacy_card_error = NOT_GIVEN, card_error: nil)
         warn_for_deprecated_arguments do |keywords|
           keywords << :card_error if legacy_card_error != NOT_GIVEN
@@ -60,15 +92,44 @@ module Faker
         fetch('stripe.invalid_cards.' + card_error)
       end
 
+      ##
+      # Produces a random month in two digits format.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Stripe.month #=> "10"
+      #
+      # @faker.version 1.9.0
       def month
         format('%02d', rand_in_range(1, 12))
       end
 
+      ##
+      # Produces a random year that is always in the future.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Stripe.year #=> "2018" # This will always be a year in the future
+      #
+      # @faker.version 1.9.0
       def year
         start_year = ::Time.new.year + 1
         rand_in_range(start_year, start_year + 5).to_s
       end
 
+      ##
+      # Produces a random ccv number.
+      #
+      # @param card_type [String] Specific valid card type.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Stripe.ccv #=> "123"
+      #   Faker::Stripe.ccv(card_type: "amex") #=> "1234"
+      #
+      # @faker.version 1.9.0
       def ccv(legacy_card_type = NOT_GIVEN, card_type: nil)
         warn_for_deprecated_arguments do |keywords|
           keywords << :card_type if legacy_card_type != NOT_GIVEN

data/lib/faker/default/twitter.rb

@@ -3,6 +3,19 @@
 module Faker
   class Twitter < Base
     class << self
+      ##
+      # Produces a random Twitter user.
+      #
+      # @param include_status [Boolean] Include or exclude user status details
+      # @param include_email [Boolean] Include or exclude user email details
+      # @return [Hash]
+      #
+      # @example
+      #   Faker::Twitter.user #=>  {:id=>8821452687517076614, :name=>"Lincoln Paucek", :screen_name=>"cody"...
+      #   Faker::Twitter.user(include_status: false) # Just get a user object with no embed status
+      #   Faker::Twitter.user(include_email: true) # Simulate an authenticated user with the email permission
+      #
+      # @faker.version 1.7.3
       def user(legacy_include_status = NOT_GIVEN, legacy_include_email = NOT_GIVEN, include_status: true, include_email: false)
         warn_for_deprecated_arguments do |keywords|
           keywords << :include_status if legacy_include_status != NOT_GIVEN
@@ -59,6 +72,19 @@ module Faker
         user
       end
 
+      ##
+      # Produces a random Twitter user.
+      #
+      # @param include_user [Boolean] Include or exclude user details
+      # @param include_photo [Boolean] Include or exclude user photo
+      # @return [Hash]
+      #
+      # @example
+      #   Faker::Twitter.status #=> {:id=>8821452687517076614, :text=>"Ea et laboriosam vel non."...
+      #   Faker::Twitter.status(include_user: false) # Just get a status object with no embed user
+      #   Faker::Twitter.status(include_photo: true) # Includes entities for an attached image
+      #
+      # @faker.version 1.7.3
       def status(legacy_include_user = NOT_GIVEN, legacy_include_photo = NOT_GIVEN, include_user: true, include_photo: false)
         warn_for_deprecated_arguments do |keywords|
           keywords << :include_user if legacy_include_user != NOT_GIVEN
@@ -97,6 +123,15 @@ module Faker
         status
       end
 
+      ##
+      # Produces a random screen name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Twitter.screen_name #=> "audreanne_hackett"
+      #
+      # @faker.version 1.7.3
       def screen_name
         Faker::Internet.username(specifier: nil, separators: ['_'])[0...20]
       end

data/lib/faker/default/types.rb

@@ -7,6 +7,15 @@ module Faker
     COMPLEX_TYPES = %i[hash array].freeze
 
     class << self
+      ##
+      # Produces a random String created from word (Faker::Lorem.word)
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Types.rb_string #=> "foobar"
+      #
+      # @faker.version 1.8.6
       def rb_string(legacy_words = NOT_GIVEN, words: 1)
         warn_for_deprecated_arguments do |keywords|
           keywords << :words if legacy_words != NOT_GIVEN
@@ -20,10 +29,28 @@ module Faker
         shuffle(word_list)[0, resolved_num].join(' ')
       end
 
+      ##
+      # Produces a random character from the a-z, 0-9 ranges.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Types.character #=> "n"
+      #
+      # @faker.version 1.8.6
       def character
         sample(CHARACTERS)
       end
 
+      ##
+      # Produces a random integer.
+      #
+      # @return [Integer]
+      #
+      # @example
+      #   Faker::Types.rb_integer #=> 1
+      #
+      # @faker.version 1.8.6
       def rb_integer(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from: 0, to: 100)
         warn_for_deprecated_arguments do |keywords|
           keywords << :from if legacy_from != NOT_GIVEN
@@ -33,6 +60,18 @@ module Faker
         rand(from..to).to_i
       end
 
+      ##
+      # Produces a random hash with random keys and values.
+      #
+      # @param number [Integer] Specifies the number of key-value pairs.
+      # @return [Hash]
+      #
+      # @example
+      #   Faker::Types.rb_hash #=> {name: "bob"}
+      #   Faker::Types.rb_hash(number: 1) #=> {name: "bob"}
+      #   Faker::Types.rb_hash(number: 2) #=> {name: "bob", last: "marley"}
+      #
+      # @faker.version 1.8.6
       def rb_hash(legacy_number = NOT_GIVEN, legacy_type = NOT_GIVEN, number: 1, type: random_type)
         warn_for_deprecated_arguments do |keywords|
           keywords << :number if legacy_number != NOT_GIVEN
@@ -46,6 +85,18 @@ module Faker
         end
       end
 
+      ##
+      # Produces a random complex hash with random keys and values where the values may include other hashes and arrays.
+      #
+      # @param number [Integer] Specifies the number of key-value pairs.
+      # @return [Hash]
+      #
+      # @example
+      #   Faker::Types.complex_rb_hash #=> {user: {first: "bob", last: "marley"}}
+      #   Faker::Types.complex_rb_hash(number: 1) #=> {user: {first: "bob", last: "marley"}}
+      #   Faker::Types.complex_rb_hash(number: 2) #=> {user: {first: "bob", last: "marley"}, son: ["damien", "marley"]}
+      #
+      # @faker.version 1.8.6
       def complex_rb_hash(legacy_number = NOT_GIVEN, number: 1)
         warn_for_deprecated_arguments do |keywords|
           keywords << :number if legacy_number != NOT_GIVEN
@@ -54,6 +105,17 @@ module Faker
         rb_hash(number: number, type: random_complex_type)
       end
 
+      ##
+      # Produces a random array.
+      #
+      # @param len [Integer] Specifies the number of elements in the array.
+      # @return [Array]
+      #
+      # @example
+      #   Faker::Types.rb_array #=> ["a"]
+      #   Faker::Types.rb_array(len: 4) #=> ["a", 1, 2, "bob"]
+      #
+      # @faker.version 1.8.6
       def rb_array(legacy_len = NOT_GIVEN, len: 1)
         warn_for_deprecated_arguments do |keywords|
           keywords << :len if legacy_len != NOT_GIVEN
@@ -66,6 +128,15 @@ module Faker
         end
       end
 
+      ##
+      # Produces a random type that's either a String or an Integer.
+      #
+      # @return [String, Integer]
+      #
+      # @example
+      #   Faker::Types.random_type #=> 1 or "a" or "bob"
+      #
+      # @faker.version 1.8.6
       def random_type
         type_to_use = SIMPLE_TYPES[rand(0..SIMPLE_TYPES.length - 1)]
         case type_to_use
@@ -76,6 +147,15 @@ module Faker
         end
       end
 
+      ##
+      # Produces a random complex type that's either a String, an Integer, an array or a hash.
+      #
+      # @return [String, Integer]
+      #
+      # @example
+      #   Faker::Types.random_complex_type #=> 1 or "a" or "bob" or {foo: "bar"}
+      #
+      # @faker.version 1.8.6
       def random_complex_type
         types = SIMPLE_TYPES + COMPLEX_TYPES
         type_to_use = types[rand(0..types.length - 1)]