faker 2.11.0 → 2.12.0

data/lib/faker/default/measurement.rb

@@ -6,6 +6,19 @@ module Faker
       ALL = 'all'
       NONE = 'none'
 
+      ##
+      # Produces a random height measurement.
+      #
+      # @param amount [Integer] Speficies the random height value.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Measurement.height #=> "6 inches"
+      #   Faker::Measurement.height(amount: 1.4) #=> "1.4 inches"
+      #   Faker::Measurement.height(amount: "none") #=> "inch"
+      #   Faker::Measurement.height(amount: "all") #=> "inches"
+      #
+      # @faker.version 1.7.3
       def height(legacy_amount = NOT_GIVEN, amount: rand(10))
         warn_for_deprecated_arguments do |keywords|
           keywords << :amount if legacy_amount != NOT_GIVEN
@@ -14,6 +27,17 @@ module Faker
         define_measurement_locale(amount, 'height')
       end
 
+      ##
+      # Produces a random length measurement.
+      #
+      # @param amount [Integer] Speficies the random length value.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Measurement.length #=> "1 yard"
+      #   Faker::Measurement.length(amount: 1.4) #=> "1.4 yards"
+      #
+      # @faker.version 1.7.3
       def length(legacy_amount = NOT_GIVEN, amount: rand(10))
         warn_for_deprecated_arguments do |keywords|
           keywords << :amount if legacy_amount != NOT_GIVEN
@@ -22,6 +46,17 @@ module Faker
         define_measurement_locale(amount, 'length')
       end
 
+      ##
+      # Produces a random volume measurement.
+      #
+      # @param amount [Integer] Speficies the random volume value.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Measurement.volume #=> "10 cups"
+      #   Faker::Measurement.volume(amount: 1.4) #=> "1.4 cups"
+      #
+      # @faker.version 1.7.3
       def volume(legacy_amount = NOT_GIVEN, amount: rand(10))
         warn_for_deprecated_arguments do |keywords|
           keywords << :amount if legacy_amount != NOT_GIVEN
@@ -30,6 +65,17 @@ module Faker
         define_measurement_locale(amount, 'volume')
       end
 
+      ##
+      # Produces a random weight measurement.
+      #
+      # @param amount [Integer] Speficies the random weight value.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Measurement.weight #=> "3 pounds"
+      #   Faker::Measurement.weight(amount: 1.4) #=> "1.4 pounds"
+      #
+      # @faker.version 1.7.3
       def weight(legacy_amount = NOT_GIVEN, amount: rand(10))
         warn_for_deprecated_arguments do |keywords|
           keywords << :amount if legacy_amount != NOT_GIVEN
@@ -38,6 +84,17 @@ module Faker
         define_measurement_locale(amount, 'weight')
       end
 
+      ##
+      # Produces a random metric height measurement.
+      #
+      # @param amount [Integer] Speficies the random height value.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Measurement.metric_height #=> "2 meters"
+      #   Faker::Measurement.metric_height(amount: 1.4) #=> "1.4 meters"
+      #
+      # @faker.version 1.7.3
       def metric_height(legacy_amount = NOT_GIVEN, amount: rand(10))
         warn_for_deprecated_arguments do |keywords|
           keywords << :amount if legacy_amount != NOT_GIVEN
@@ -46,6 +103,17 @@ module Faker
         define_measurement_locale(amount, 'metric_height')
       end
 
+      ##
+      # Produces a random metric length measurement.
+      #
+      # @param amount [Integer] Speficies the random length value.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Measurement.metric_length #=> "0 decimeters"
+      #   Faker::Measurement.metric_length(amount: 1.4) #=> "1.4 decimeters"
+      #
+      # @faker.version 1.7.3
       def metric_length(legacy_amount = NOT_GIVEN, amount: rand(10))
         warn_for_deprecated_arguments do |keywords|
           keywords << :amount if legacy_amount != NOT_GIVEN
@@ -54,6 +122,17 @@ module Faker
         define_measurement_locale(amount, 'metric_length')
       end
 
+      ##
+      # Produces a random metric volume measurement.
+      #
+      # @param amount [Integer] Speficies the random volume value.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Measurement.metric_volume #=> "1 liter"
+      #   Faker::Measurement.metric_volume(amount: 1.4) #=> "1.4 liters"
+      #
+      # @faker.version 1.7.3
       def metric_volume(legacy_amount = NOT_GIVEN, amount: rand(10))
         warn_for_deprecated_arguments do |keywords|
           keywords << :amount if legacy_amount != NOT_GIVEN
@@ -62,6 +141,17 @@ module Faker
         define_measurement_locale(amount, 'metric_volume')
       end
 
+      ##
+      # Produces a random metric weight measurement.
+      #
+      # @param amount [Integer] Speficies the random weight value.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Measurement.metric_weight #=> "8 grams"
+      #   Faker::Measurement.metric_weight(amount: 1.4) #=> "1.4 grams"
+      #
+      # @faker.version 1.7.3
       def metric_weight(legacy_amount = NOT_GIVEN, amount: rand(10))
         warn_for_deprecated_arguments do |keywords|
           keywords << :amount if legacy_amount != NOT_GIVEN

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,87 @@ 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 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/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

data/lib/faker/default/slack_emoji.rb

@@ -3,38 +3,119 @@
 module Faker
   class SlackEmoji < Base
     class << self
+      ##
+      # Produces a random slack emoji from people category.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SlackEmoji.people #=> ":sleepy:"
+      #
+      # @faker.version 1.5.0
       def people
         fetch('slack_emoji.people')
       end
 
+      ##
+      # Produces a random slack emoji from nature category.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SlackEmoji.nature #=> ":mount_fuji:"
+      #
+      # @faker.version 1.5.0
       def nature
         fetch('slack_emoji.nature')
       end
 
+      ##
+      # Produces a random slack emoji from food and drink category.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SlackEmoji.food_and_drink #=> ":beers:"
+      #
+      # @faker.version 1.5.0
       def food_and_drink
         fetch('slack_emoji.food_and_drink')
       end
 
+      ##
+      # Produces a random slack emoji from celebration category.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SlackEmoji.celebration #=> ":tada:"
+      #
+      # @faker.version 1.5.0
       def celebration
         fetch('slack_emoji.celebration')
       end
 
+      ##
+      # Produces a random slack emoji from activity category.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SlackEmoji.activity #=> ":soccer:"
+      #
+      # @faker.version 1.5.0
       def activity
         fetch('slack_emoji.activity')
       end
 
+      ##
+      # Produces a random slack emoji from travel and places category.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SlackEmoji.travel_and_places #=> ":metro:"
+      #
+      # @faker.version 1.5.0
       def travel_and_places
         fetch('slack_emoji.travel_and_places')
       end
 
+      ##
+      # Produces a random slack emoji from objects and symbols category.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SlackEmoji.objects_and_symbols #=> ":id:"
+      #
+      # @faker.version 1.5.0
       def objects_and_symbols
         fetch('slack_emoji.objects_and_symbols')
       end
 
+      ##
+      # Produces a random slack emoji from custom category.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SlackEmoji.custom #=> ":slack:"
+      #
+      # @faker.version 1.5.0
       def custom
         fetch('slack_emoji.custom')
       end
 
+      ##
+      # Produces a random slack emoji from any category.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SlackEmoji.emoji #=> ":pizza:"
+      #
+      # @faker.version 1.5.0
       def emoji
         parse('slack_emoji.emoji')
       end