faker 2.11.0 → 2.13.0

data/lib/faker/default/name.rb

@@ -5,14 +5,41 @@ module Faker
     flexible :name
 
     class << self
+      ##
+      # Produces a random name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Name.name #=> "Tyshawn Johns Sr."
+      #
+      # @faker.version 0.9.0
       def name
         parse('name.name')
       end
 
+      ##
+      # Produces a random name with middle name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Name.name_with_middle #=> "Aditya Elton Douglas"
+      #
+      # @faker.version 1.6.4
       def name_with_middle
         parse('name.name_with_middle')
       end
 
+      ##
+      # Produces a random first name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Name.first_name #=> "Kaci"
+      #
+      # @faker.version 0.9.0
       def first_name
         if parse('name.first_name').empty?
           fetch('name.first_name')
@@ -21,31 +48,102 @@ module Faker
         end
       end
 
+      ##
+      # Produces a random male first name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Name.male_first_name #=> "Edward"
+      #
+      # @faker.version 1.9.1
       def male_first_name
         fetch('name.male_first_name')
       end
       alias first_name_men male_first_name
       alias masculine_name male_first_name
 
+      ##
+      # Produces a random female first name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Name.female_first_name #=> "Natasha"
+      #
+      # @faker.version 1.9.1
       def female_first_name
         fetch('name.female_first_name')
       end
       alias first_name_women female_first_name
       alias feminine_name female_first_name
 
+      ##
+      # Produces a random gender neutral first name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Name.neutral_first_name #=> "Casey"
+      #
+      # @faker.version 2.13.0
+      def neutral_first_name
+        fetch('name.neutral_first_name')
+      end
+      alias first_name_neutral neutral_first_name
+      alias gender_neutral_first_name neutral_first_name
+
+      ##
+      # Produces a random last name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Name.last_name #=> "Ernser"
+      #
+      # @faker.version 0.9.0
       def last_name
         parse('name.last_name')
       end
       alias middle_name last_name
 
+      ##
+      # Produces a random name prefix.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Name.prefix #=> "Mr."
+      #
+      # @faker.version 0.9.0
       def prefix
         fetch('name.prefix')
       end
 
+      ##
+      # Produces a random name suffix.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Name.suffix #=> "IV"
+      #
+      # @faker.version 0.9.0
       def suffix
         fetch('name.suffix')
       end
 
+      ##
+      # Produces random initials.
+      #
+      # @param number [Integer] Number of digits that the generated initials should have.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Name.initials            #=> "NJM"
+      #   Faker::Name.initials(number: 2) #=> "NM"
+      #
+      # @faker.version 1.8.5
       def initials(legacy_number = NOT_GIVEN, number: 3)
         warn_for_deprecated_arguments do |keywords|
           keywords << :number if legacy_number != NOT_GIVEN

data/lib/faker/default/nhs.rb

@@ -3,6 +3,15 @@
 module Faker
   class NationalHealthService < Base
     class << self
+      ##
+      # Produces a random British NHS number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::NationalHealthService.british_number #=> "403 958 5577"
+      #
+      # @faker.version 1.9.2
       def british_number
         base_number = rand(400_000_001...499_999_999)
         # If the check digit is equivalent to 10, the number is invalid.
@@ -15,6 +24,16 @@ module Faker
                                                            .join('')
       end
 
+      ##
+      # Produces a random British NHS number's check digit.
+      #
+      # @param number [Integer] Specifies the NHS number the check digit belongs to.
+      # @return [Integer]
+      #
+      # @example
+      #   Faker::NationalHealthService.check_digit(number: 400_012_114) #=> 6
+      #
+      # @faker.version 1.9.2
       def check_digit(legacy_number = NOT_GIVEN, number: 0)
         warn_for_deprecated_arguments do |keywords|
           keywords << :number if legacy_number != NOT_GIVEN

data/lib/faker/default/number.rb

@@ -85,13 +85,11 @@ module Faker
         end
 
         l_d = number(digits: l_digits)
-        r_d = if r_digits == 1
-                generate(r_digits)
-              else
-                # Ensure the last digit is not zero
-                # so it does not get truncated on converting to float
-                generate(r_digits - 1).join + non_zero_digit.to_s
-              end
+
+        # Ensure the last digit is not zero
+        # so it does not get truncated on converting to float
+        r_d = generate(r_digits - 1).join + non_zero_digit.to_s
+
         "#{l_d}.#{r_d}".to_f
       end
 

data/lib/faker/default/omniauth.rb

@@ -15,6 +15,16 @@ module Faker
     end
 
     class << self
+      ##
+      # Generate a mock Omniauth response from Google.
+      #
+      # @param name [String] A specific name to return in the response.
+      # @param email [String] A specific email to return in the response.
+      # @param uid [String] A specific UID to return in the response.
+      #
+      # @return [Hash] An auth hash in the format provided by omniauth-google.
+      #
+      # @faker.version 1.8.0
       # rubocop:disable Metrics/ParameterLists
       def google(legacy_name = NOT_GIVEN, legacy_email = NOT_GIVEN, legacy_uid = NOT_GIVEN, name: nil, email: nil, uid: Number.number(digits: 9).to_s)
         # rubocop:enable Metrics/ParameterLists
@@ -72,6 +82,17 @@ module Faker
         }
       end
 
+      ##
+      # Generate a mock Omniauth response from Facebook.
+      #
+      # @param name [String] A specific name to return in the response.
+      # @param email [String] A specific email to return in the response.
+      # @param username [String] A specific username to return in the response.
+      # @param uid [String] A specific UID to return in the response.
+      #
+      # @return [Hash] An auth hash in the format provided by omniauth-facebook.
+      #
+      # @faker.version 1.8.0
       # rubocop:disable Metrics/ParameterLists
       def facebook(legacy_name = NOT_GIVEN, legacy_email = NOT_GIVEN, legacy_username = NOT_GIVEN, legacy_uid = NOT_GIVEN, name: nil, email: nil, username: nil, uid: Number.number(digits: 7).to_s)
         # rubocop:enable Metrics/ParameterLists
@@ -123,6 +144,16 @@ module Faker
         }
       end
 
+      ##
+      # Generate a mock Omniauth response from Twitter.
+      #
+      # @param name [String] A specific name to return in the response.
+      # @param nickname [String] A specific nickname to return in the response.
+      # @param uid [String] A specific UID to return in the response.
+      #
+      # @return [Hash] An auth hash in the format provided by omniauth-twitter.
+      #
+      # @faker.version 1.8.0
       # rubocop:disable Metrics/ParameterLists
       def twitter(legacy_name = NOT_GIVEN, legacy_nickname = NOT_GIVEN, legacy_uid = NOT_GIVEN, name: nil, nickname: nil, uid: Number.number(digits: 6).to_s)
         # rubocop:enable Metrics/ParameterLists
@@ -204,6 +235,16 @@ module Faker
         }
       end
 
+      ##
+      # Generate a mock Omniauth response from LinkedIn.
+      #
+      # @param name [String] A specific name to return in the response.
+      # @param email [String] A specific email to return in the response.
+      # @param uid [String] A specific UID to return in the response.
+      #
+      # @return [Hash] An auth hash in the format provided by omniauth-linkedin.
+      #
+      # @faker.version 1.8.0
       # rubocop:disable Metrics/ParameterLists
       def linkedin(legacy_name = NOT_GIVEN, legacy_email = NOT_GIVEN, legacy_uid = NOT_GIVEN, name: nil, email: nil, uid: Number.number(digits: 6).to_s)
         # rubocop:enable Metrics/ParameterLists
@@ -275,6 +316,16 @@ module Faker
         }
       end
 
+      ##
+      # Generate a mock Omniauth response from Github.
+      #
+      # @param name [String] A specific name to return in the response.
+      # @param email [String] A specific email to return in the response.
+      # @param uid [String] A specific UID to return in the response.
+      #
+      # @return [Hash] An auth hash in the format provided by omniauth-github.
+      #
+      # @faker.version 1.8.0
       # rubocop:disable Metrics/ParameterLists
       def github(legacy_name = NOT_GIVEN, legacy_email = NOT_GIVEN, legacy_uid = NOT_GIVEN, name: nil, email: nil, uid: Number.number(digits: 8).to_s)
         # rubocop:enable Metrics/ParameterLists
@@ -342,13 +393,15 @@ module Faker
       end
 
       ##
-      # Generate a mock Omniauth response from Apple
+      # Generate a mock Omniauth response from Apple.
+      #
+      # @param name [String] A specific name to return in the response.
+      # @param email [String] A specific email to return in the response.
+      # @param uid [String] A specific UID to return in the response.
       #
-      # @param name [String] A specific name to return in the response
-      # @param email [String] A specific email to return in the response
-      # @param uid [String] A specific UID to return in the response
+      # @return [Hash] An auth hash in the format provided by omniauth-apple.
       #
-      # @return [Hash] An auth hash in the format provided by omniauth-apple
+      # @faker.version 2.3.0
       def apple(name: nil, email: nil, uid: nil)
         uid ||= "#{Number.number(digits: 6)}.#{Number.hexadecimal(digits: 32)}.#{Number.number(digits: 4)}"
         auth = Omniauth.new(name: name, email: email)

data/lib/faker/default/phone_number.rb

@@ -3,43 +3,126 @@
 module Faker
   class PhoneNumber < Base
     class << self
+      ##
+      # Produces a random phone number in a random format (may or may not have a country code, extension and can have different dividers).
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::PhoneNumber.phone_number #=> "397.693.1309 x4321"
+      #
+      # @faker.version 0.3.0
       def phone_number
         parse('phone_number.formats')
       end
 
+      ##
+      # Produces a random cell phone number in a random format (may or may not have a country code and can have different dividers).
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::PhoneNumber.cell_phone #=> "(186)285-7925"
+      #
+      # @faker.version 1.0.0
       def cell_phone
         parse('cell_phone.formats')
       end
 
+      ##
+      # Produces a random country code.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::PhoneNumber.country_code #=> "+20"
+      #
+      # @faker.version 1.9.2
       def country_code
         "+#{fetch('country_code')}"
       end
 
+      ##
+      # Produces a random phone number with country code.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::PhoneNumber.phone_number_with_country_code #=> "+95 1-672-173-8153"
+      #
+      # @faker.version 1.9.2
       def phone_number_with_country_code
         "#{country_code} #{phone_number}"
       end
 
+      ##
+      # Produces a random cell phone number with country code.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::PhoneNumber.cell_phone_with_country_code #=> "+974 (190) 987-9034"
+      #
+      # @faker.version 1.9.2
       def cell_phone_with_country_code
         "#{country_code} #{cell_phone}"
       end
 
-      # US and Canada only
+      ##
+      # Produces a random phone number in e164 format.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::PhoneNumber.cell_phone_in_e164 #=> "+944937040625"
+      #
+      # @faker.version 1.9.2
+      def cell_phone_in_e164
+        cell_phone_with_country_code.delete('^+0-9')
+      end
+
+      ##
+      # Produces a random US or Canada-based area code.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::PhoneNumber.area_code #=> "201"
+      #
+      # @faker.version 1.3.0
       def area_code
         fetch('phone_number.area_code')
       rescue I18n::MissingTranslationData
         nil
       end
 
-      # US and Canada only
+      ##
+      # Produces a random US or Canada-based exchange code.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::PhoneNumber.exchange_code #=> "208"
+      #
+      # @faker.version 1.3.0
       def exchange_code
         fetch('phone_number.exchange_code')
       rescue I18n::MissingTranslationData
         nil
       end
 
-      # US and Canada only
-      # Can be used for both extensions and last four digits of phone number.
-      # Since extensions can be of variable length, this method taks a length parameter
+      ##
+      # Produces a random US or Canada-based extension / subscriber number. Can be used for both extensions and last four digits of phone number.
+      #
+      # @param length [Integer] Speficies the length of the return value.
+      # @return [String]
+      #
+      # @example
+      #   Faker::PhoneNumber.subscriber_number #=> "3873"
+      #   Faker::PhoneNumber.subscriber_number(length: 2) #=> "39"
+      #   Faker::PhoneNumber.extension #=> "3764"
+      #
+      # @faker.version 1.3.0
       def subscriber_number(legacy_length = NOT_GIVEN, length: 4)
         warn_for_deprecated_arguments do |keywords|
           keywords << :length if legacy_length != NOT_GIVEN

data/lib/faker/default/placeholdit.rb

@@ -5,6 +5,27 @@ module Faker
     class << self
       SUPPORTED_FORMATS = %w[png jpg gif jpeg].freeze
 
+      ##
+      # Produces a random placeholder image from https://placehold.it.
+      #
+      # @param size [String] Specifies the image's size, dimensions separated by 'x'.
+      # @param format [String] Specifies the image's extension.
+      # @param background_color [String, Symbol] Specifies the background color, either in hexadecimal format (without #) or as :random.
+      # @param text_color [String, Symbol] Specifies the text color, either in hexadecimal format (without #) or as :random.
+      # @param text [String] Specifies a custom text to be used.
+      # @return [String]
+      #
+      # @example
+      #     # Keyword arguments: size, format, background_color, text_color, text
+      #   Faker::Placeholdit.image #=> "https://placehold.it/300x300.png"
+      #   Faker::Placeholdit.image(size: '50x50') #=> "https://placehold.it/50x50.png"
+      #   Faker::Placeholdit.image(size: '50x50', format: 'jpg') #=> "https://placehold.it/50x50.jpg"
+      #   Faker::Placeholdit.image(size: '50x50', format: 'gif', background_color: 'ffffff') #=> "https://placehold.it/50x50.gif/ffffff"
+      #   Faker::Placeholdit.image(size: '50x50', format: 'jpeg', background_color: :random) #=> "https://placehold.it/50x50.jpeg/39eba7"
+      #   Faker::Placeholdit.image(size: '50x50', format: 'jpeg', background_color: 'ffffff', text_color: '000') #=> "https://placehold.it/50x50.jpeg/ffffff/000"
+      #   Faker::Placeholdit.image(size: '50x50', format: 'jpg', background_color: 'ffffff', text_color: '000', text: 'Some Custom Text') #=> "https://placehold.it/50x50.jpg/ffffff/000?text=Some Custom Text"
+      #
+      # @faker.version 1.6.0
       # rubocop:disable Metrics/ParameterLists
       def image(legacy_size = NOT_GIVEN, legacy_format = NOT_GIVEN, legacy_background_color = NOT_GIVEN, legacy_text_color = NOT_GIVEN, legacy_text = NOT_GIVEN, size: '300x300', format: 'png', background_color: nil, text_color: nil, text: nil)
         # rubocop:enable Metrics/ParameterLists