faker 2.9.0 → 2.12.0

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)]

data/lib/faker/default/university.rb

@@ -5,22 +5,67 @@ module Faker
     flexible :university
 
     class << self
+      ##
+      # Produces a random university name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::University.name #=> "Eastern Mississippi Academy"
+      #
+      # @faker.version 1.5.0
       def name
         parse('university.name')
       end
 
+      ##
+      # Produces a random university prefix.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::University.prefix #=> "Western"
+      #
+      # @faker.version 1.5.0
       def prefix
         fetch('university.prefix')
       end
 
+      ##
+      # Produces a random university suffix.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::University.suffix #=> "Academy"
+      #
+      # @faker.version 1.5.0
       def suffix
         fetch('university.suffix')
       end
 
+      ##
+      # Produces a random greek organization.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::University.greek_organization #=> "BEX"
+      #
+      # @faker.version 1.5.0
       def greek_organization
         Array.new(3) { |_| sample(greek_alphabet) }.join
       end
 
+      ##
+      # Produces a greek alphabet.
+      #
+      # @return [Array]
+      #
+      # @example
+      #   Faker::University.greek_alphabet #=> ["Α", "B", "Γ", "Δ", ...]
+      #
+      # @faker.version 1.5.0
       def greek_alphabet
         %w[Α B Γ Δ E Z H Θ I K Λ M N Ξ
            O Π P Σ T Y Φ X Ψ Ω]

data/lib/faker/default/vehicle.rb

@@ -14,18 +14,54 @@ module Faker
     SG_CHECKSUM_CHARS = 'AYUSPLJGDBZXTRMKHEC'
 
     class << self
+      # Produces a random vehicle VIN number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Vehicle.vin #=> "LLDWXZLG77VK2LUUF"
+      #
+      # @faker.version 1.6.4
       def vin
         regexify(VIN_REGEX)
       end
 
+      # Produces a random vehicle manufacturer.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Vehicle.manufacture #=> "Lamborghini"
+      #
+      # @faker.version 1.6.4
       def manufacture
         fetch('vehicle.manufacture')
       end
 
+      ##
+      # Produces a random vehicle make.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Vehicle.make #=> "Honda"
+      #
+      # @faker.version 1.6.4
       def make
         fetch('vehicle.makes')
       end
 
+      ##
+      # Produces a random vehicle model.
+      #
+      # @param make_of_model [String] Specific valid vehicle make.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Vehicle.model #=> "A8"
+      #   Faker::Vehicle.model(make_of_model: 'Toyota') #=> "Prius"
+      #
+      # @faker.version 1.6.4
       def model(legacy_make_of_model = NOT_GIVEN, make_of_model: '')
         warn_for_deprecated_arguments do |keywords|
           keywords << :make_of_model if legacy_make_of_model != NOT_GIVEN
@@ -36,59 +72,183 @@ module Faker
         fetch("vehicle.models_by_make.#{make_of_model}")
       end
 
+      ##
+      # Produces a random vehicle make and model.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Vehicle.make_and_model #=> "Dodge Charger"
+      #
+      # @faker.version 1.6.4
       def make_and_model
         m = make
 
         "#{m} #{model(make_of_model: m)}"
       end
 
+      ##
+      # Produces a random vehicle style.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Vehicle.style #=> "ESi"
+      #
+      # @faker.version 1.6.4
       def style
         fetch('vehicle.styles')
       end
 
+      ##
+      # Produces a random vehicle color.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Vehicle.color #=> "Red"
+      #
+      # @faker.version 1.6.4
       def color
         fetch('vehicle.colors')
       end
 
+      ##
+      # Produces a random vehicle transmission.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Vehicle.transmission #=> "Automanual"
+      #
+      # @faker.version 1.6.4
       def transmission
         fetch('vehicle.transmissions')
       end
 
+      ##
+      # Produces a random vehicle drive type.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Vehicle.drive_type #=> "4x2/2-wheel drive"
+      #
+      # @faker.version 1.6.4
       def drive_type
         fetch('vehicle.drive_types')
       end
 
+      ##
+      # Produces a random vehicle fuel type.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Vehicle.fuel_type #=> "Diesel"
+      #
+      # @faker.version 1.6.4
       def fuel_type
         fetch('vehicle.fuel_types')
       end
 
+      ##
+      # Produces a random car type.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Vehicle.car_type #=> "Sedan"
+      #
+      # @faker.version 1.6.4
       def car_type
         fetch('vehicle.car_types')
       end
 
+      ##
+      # Produces a random engine cylinder count.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Vehicle.engine_size #=> 6
+      #   Faker::Vehicle.engine #=> 4
+      #
+      # @faker.version 1.6.4
       def engine
         "#{sample(fetch_all('vehicle.doors'))} #{fetch('vehicle.cylinder_engine')}"
       end
 
       alias engine_size engine
 
+      ##
+      # Produces a random list of car options.
+      #
+      # @return [Array<String>]
+      #
+      # @example
+      #   Faker::Vehicle.car_options #=> ["DVD System", "MP3 (Single Disc)", "Tow Package", "CD (Multi Disc)", "Cassette Player", "Bucket Seats", "Cassette Player", "Leather Interior", "AM/FM Stereo", "Third Row Seats"]
+      #
+      # @faker.version 1.6.4
       def car_options
         Array.new(rand(5...10)) { fetch('vehicle.car_options') }
       end
 
+      ##
+      # Produces a random list of standard specs.
+      #
+      # @return [Array<String>]
+      #
+      # @example
+      #   Faker::Vehicle.standard_specs #=> ["Full-size spare tire w/aluminum alloy wheel", "Back-up camera", "Carpeted cargo area", "Silver accent IP trim finisher -inc: silver shifter finisher", "Back-up camera", "Water-repellent windshield & front door glass", "Floor carpeting"]
+      #
+      # @faker.version 1.6.4
       def standard_specs
         Array.new(rand(5...10)) { fetch('vehicle.standard_specs') }
       end
 
+      ##
+      # Produces a random vehicle door count.
+      #
+      # @return [Integer]
+      #
+      # @example
+      #   Faker::Vehicle.doors #=> 1
+      #   Faker::Vehicle.door_count #=> 3
+      #
+      # @faker.version 1.6.4
       def doors
         sample(fetch_all('vehicle.doors'))
       end
       alias door_count doors
 
+      ##
+      # Produces a random car year between 1 and 15 years ago.
+      #
+      # @return [Integer]
+      #
+      # @example
+      #   Faker::Vehicle.year #=> 2008
+      #
+      # @faker.version 1.6.4
       def year
         Faker::Time.backward(days: rand_in_range(365, 5475), period: :all, format: '%Y').to_i
       end
 
+      ##
+      # Produces a random mileage/kilometrage for a vehicle.
+      #
+      # @param min [Integer] Specific minimum limit for mileage generation.
+      # @param max [Integer] Specific maximum limit for mileage generation.
+      # @return [Integer]
+      #
+      # @example
+      #   Faker::Vehicle.mileage #=> 26961
+      #   Faker::Vehicle.mileage(min: 50_000) #=> 81557
+      #   Faker::Vehicle.mileage(min: 50_000, max: 250_000) #=> 117503
+      #   Faker::Vehicle.kilometrage #=> 35378
+      #
+      # @faker.version 1.6.4
       def mileage(legacy_min = NOT_GIVEN, legacy_max = NOT_GIVEN, min: MILEAGE_MIN, max: MILEAGE_MAX)
         warn_for_deprecated_arguments do |keywords|
           keywords << :min if legacy_min != NOT_GIVEN
@@ -100,17 +260,37 @@ module Faker
 
       alias kilometrage mileage
 
-      def license_plate(legacy_state_abreviation = NOT_GIVEN, state_abreviation: '')
+      ##
+      # Produces a random license plate number.
+      #
+      # @param state_abbreviation [String] Two letter state abbreviation for license plate generation.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Vehicle.license_plate #=> "DEP-2483"
+      #   Faker::Vehicle.license_plate(state_abbreviation: 'FL') #=> "977 UNU"
+      #
+      # @faker.version 1.6.4
+      def license_plate(legacy_state_abreviation = NOT_GIVEN, state_abbreviation: '')
         warn_for_deprecated_arguments do |keywords|
-          keywords << :state_abreviation if legacy_state_abreviation != NOT_GIVEN
+          keywords << :state_abbreviation if legacy_state_abreviation != NOT_GIVEN
         end
 
-        return regexify(bothify(fetch('vehicle.license_plate'))) if state_abreviation.empty?
+        return regexify(bothify(fetch('vehicle.license_plate'))) if state_abbreviation.empty?
 
-        key = 'vehicle.license_plate_by_state.' + state_abreviation
+        key = 'vehicle.license_plate_by_state.' + state_abbreviation
         regexify(bothify(fetch(key)))
       end
 
+      ##
+      # Produces a random license plate number for Singapore.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Vehicle.singapore_license_plate #=> "SLV1854M"
+      #
+      # @faker.version 1.6.4
       def singapore_license_plate
         key = 'vehicle.license_plate'
         plate_number = regexify(bothify(fetch(key)))