faker 2.2.0 → 2.5.0

data/lib/faker/default/lorem_flickr.rb

@@ -8,17 +8,10 @@ module Faker
       # rubocop:disable Metrics/ParameterLists
       def image(legacy_size = NOT_GIVEN, legacy_search_terms = NOT_GIVEN, legacy_match_all = NOT_GIVEN, size: '300x300', search_terms: [], match_all: false)
         # rubocop:enable Metrics/ParameterLists
-        if legacy_size != NOT_GIVEN
-          warn_with_uplevel 'Passing `size` with the 1st argument of `LoremFlickr.image` is deprecated. Use keyword argument like `LoremFlickr.image(size: ...)` instead.', uplevel: 1
-          size = legacy_size
-        end
-        if legacy_search_terms != NOT_GIVEN
-          warn_with_uplevel 'Passing `search_terms` with the 2nd argument of `LoremFlickr.image` is deprecated. Use keyword argument like `LoremFlickr.image(search_terms: ...)` instead.', uplevel: 1
-          search_terms = legacy_search_terms
-        end
-        if legacy_match_all != NOT_GIVEN
-          warn_with_uplevel 'Passing `match_all` with the 3rd argument of `LoremFlickr.image` is deprecated. Use keyword argument like `LoremFlickr.image(match_all: ...)` instead.', uplevel: 1
-          match_all = legacy_match_all
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :size if legacy_size != NOT_GIVEN
+          keywords << :search_terms if legacy_search_terms != NOT_GIVEN
+          keywords << :match_all if legacy_match_all != NOT_GIVEN
         end
 
         build_url(size, nil, search_terms, match_all)
@@ -27,17 +20,10 @@ module Faker
       # rubocop:disable Metrics/ParameterLists
       def grayscale_image(legacy_size = NOT_GIVEN, legacy_search_terms = NOT_GIVEN, legacy_match_all = NOT_GIVEN, size: '300x300', search_terms: ['all'], match_all: false)
         # rubocop:enable Metrics/ParameterLists
-        if legacy_size != NOT_GIVEN
-          warn_with_uplevel 'Passing `size` with the 1st argument of `LoremFlickr.grayscale_image` is deprecated. Use keyword argument like `LoremFlickr.grayscale_image(size: ...)` instead.', uplevel: 1
-          size = legacy_size
-        end
-        if legacy_search_terms != NOT_GIVEN
-          warn_with_uplevel 'Passing `search_terms` with the 2nd argument of `LoremFlickr.grayscale_image` is deprecated. Use keyword argument like `LoremFlickr.grayscale_image(search_terms: ...)` instead.', uplevel: 1
-          search_terms = legacy_search_terms
-        end
-        if legacy_match_all != NOT_GIVEN
-          warn_with_uplevel 'Passing `match_all` with the 3rd argument of `LoremFlickr.grayscale_image` is deprecated. Use keyword argument like `LoremFlickr.grayscale_image(match_all: ...)` instead.', uplevel: 1
-          match_all = legacy_match_all
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :size if legacy_size != NOT_GIVEN
+          keywords << :search_terms if legacy_search_terms != NOT_GIVEN
+          keywords << :match_all if legacy_match_all != NOT_GIVEN
         end
 
         raise ArgumentError, 'Search terms must be specified for grayscale images' unless search_terms.any?
@@ -48,17 +34,10 @@ module Faker
       # rubocop:disable Metrics/ParameterLists
       def pixelated_image(legacy_size = NOT_GIVEN, legacy_search_terms = NOT_GIVEN, legacy_match_all = NOT_GIVEN, size: '300x300', search_terms: ['all'], match_all: false)
         # rubocop:enable Metrics/ParameterLists
-        if legacy_size != NOT_GIVEN
-          warn_with_uplevel 'Passing `size` with the 1st argument of `LoremFlickr.pixelated_image` is deprecated. Use keyword argument like `LoremFlickr.pixelated_image(size: ...)` instead.', uplevel: 1
-          size = legacy_size
-        end
-        if legacy_search_terms != NOT_GIVEN
-          warn_with_uplevel 'Passing `search_terms` with the 2nd argument of `LoremFlickr.pixelated_image` is deprecated. Use keyword argument like `LoremFlickr.pixelated_image(search_terms: ...)` instead.', uplevel: 1
-          search_terms = legacy_search_terms
-        end
-        if legacy_match_all != NOT_GIVEN
-          warn_with_uplevel 'Passing `match_all` with the 3rd argument of `LoremFlickr.pixelated_image` is deprecated. Use keyword argument like `LoremFlickr.pixelated_image(match_all: ...)` instead.', uplevel: 1
-          match_all = legacy_match_all
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :size if legacy_size != NOT_GIVEN
+          keywords << :search_terms if legacy_search_terms != NOT_GIVEN
+          keywords << :match_all if legacy_match_all != NOT_GIVEN
         end
 
         raise ArgumentError, 'Search terms must be specified for pixelated images' unless search_terms.any?
@@ -69,21 +48,11 @@ module Faker
       # rubocop:disable Metrics/ParameterLists
       def colorized_image(legacy_size = NOT_GIVEN, legacy_color = NOT_GIVEN, legacy_search_terms = NOT_GIVEN, legacy_match_all = NOT_GIVEN, size: '300x300', color: 'red', search_terms: ['all'], match_all: false)
         # rubocop:enable Metrics/ParameterLists
-        if legacy_size != NOT_GIVEN
-          warn_with_uplevel 'Passing `size` with the 1st argument of `LoremFlickr.colorized_image` is deprecated. Use keyword argument like `LoremFlickr.colorized_image(size: ...)` instead.', uplevel: 1
-          size = legacy_size
-        end
-        if legacy_color != NOT_GIVEN
-          warn_with_uplevel 'Passing `color` with the 2nd argument of `LoremFlickr.colorized_image` is deprecated. Use keyword argument like `LoremFlickr.colorized_image(color: ...)` instead.', uplevel: 1
-          color = legacy_color
-        end
-        if legacy_search_terms != NOT_GIVEN
-          warn_with_uplevel 'Passing `search_terms` with the 3rd argument of `LoremFlickr.colorized_image` is deprecated. Use keyword argument like `LoremFlickr.colorized_image(search_terms: ...)` instead.', uplevel: 1
-          search_terms = legacy_search_terms
-        end
-        if legacy_match_all != NOT_GIVEN
-          warn_with_uplevel 'Passing `match_all` with the 4th argument of `LoremFlickr.colorized_image` is deprecated. Use keyword argument like `LoremFlickr.colorized_image(match_all: ...)` instead.', uplevel: 1
-          match_all = legacy_match_all
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :size if legacy_size != NOT_GIVEN
+          keywords << :color if legacy_color != NOT_GIVEN
+          keywords << :search_terms if legacy_search_terms != NOT_GIVEN
+          keywords << :match_all if legacy_match_all != NOT_GIVEN
         end
 
         raise ArgumentError, 'Search terms must be specified for colorized images' unless search_terms.any?

data/lib/faker/default/lorem_pixel.rb

@@ -19,29 +19,13 @@ module Faker
 
       # rubocop:disable Metrics/ParameterLists
       def image(legacy_size = NOT_GIVEN, legacy_is_gray = NOT_GIVEN, legacy_category = NOT_GIVEN, legacy_number = NOT_GIVEN, legacy_text = NOT_GIVEN, legacy_secure = NOT_GIVEN, size: '300x300', is_gray: false, category: nil, number: nil, text: nil, secure: true)
-        if legacy_size != NOT_GIVEN
-          warn_with_uplevel 'Passing `size` with the 1st argument of `LoremPixel.image` is deprecated. Use keyword argument like `LoremPixel.image(size: ...)` instead.', uplevel: 1
-          size = legacy_size
-        end
-        if legacy_is_gray != NOT_GIVEN
-          warn_with_uplevel 'Passing `is_gray` with the 2nd argument of `LoremPixel.image` is deprecated. Use keyword argument like `LoremPixel.image(is_gray: ...)` instead.', uplevel: 1
-          is_gray = legacy_is_gray
-        end
-        if legacy_category != NOT_GIVEN
-          warn_with_uplevel 'Passing `category` with the 3rd argument of `LoremPixel.image` is deprecated. Use keyword argument like `LoremPixel.image(category: ...)` instead.', uplevel: 1
-          category = legacy_category
-        end
-        if legacy_number != NOT_GIVEN
-          warn_with_uplevel 'Passing `number` with the 4th argument of `LoremPixel.image` is deprecated. Use keyword argument like `LoremPixel.image(number: ...)` instead.', uplevel: 1
-          number = legacy_number
-        end
-        if legacy_text != NOT_GIVEN
-          warn_with_uplevel 'Passing `text` with the 5th argument of `LoremPixel.image` is deprecated. Use keyword argument like `LoremPixel.image(text: ...)` instead.', uplevel: 1
-          text = legacy_text
-        end
-        if legacy_secure != NOT_GIVEN
-          warn_with_uplevel 'Passing `secure` with the 6th argument of `LoremPixel.image` is deprecated. Use keyword argument like `LoremPixel.image(secure: ...)` instead.', uplevel: 1
-          secure = legacy_secure
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :size if legacy_size != NOT_GIVEN
+          keywords << :is_gray if legacy_is_gray != NOT_GIVEN
+          keywords << :category if legacy_category != NOT_GIVEN
+          keywords << :number if legacy_number != NOT_GIVEN
+          keywords << :text if legacy_text != NOT_GIVEN
+          keywords << :secure if legacy_secure != NOT_GIVEN
         end
 
         raise ArgumentError, 'Size should be specified in format 300x300' unless size =~ /^[0-9]+x[0-9]+$/

data/lib/faker/default/markdown.rb

@@ -60,13 +60,9 @@ module Faker
       end
 
       def sandwich(legacy_sentences = NOT_GIVEN, legacy_repeat = NOT_GIVEN, sentences: 3, repeat: 1)
-        if legacy_sentences != NOT_GIVEN
-          warn_with_uplevel 'Passing `sentences` with the 1st argument of `Markdown.sandwich` is deprecated. Use keyword argument like `Markdown.sandwich(sentences: ...)` instead.', uplevel: 1
-          sentences = legacy_sentences
-        end
-        if legacy_repeat != NOT_GIVEN
-          warn_with_uplevel 'Passing `repeat` with the 2nd argument of `Markdown.sandwich` is deprecated. Use keyword argument like `Markdown.sandwich(repeat: ...)` instead.', uplevel: 1
-          repeat = legacy_repeat
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :sentences if legacy_sentences != NOT_GIVEN
+          keywords << :repeat if legacy_repeat != NOT_GIVEN
         end
 
         text_block = []

data/lib/faker/default/marketing.rb

@@ -5,6 +5,15 @@ module Faker
     flexible :marketing
 
     class << self
+      ##
+      # Produces the name of a video game console or platform.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Marketing.buzzwords #=> "rubber meets the road"
+      #
+      # @faker.version 1.9.4
       def buzzwords
         fetch('marketing.buzzwords')
       end

data/lib/faker/default/measurement.rb

@@ -7,72 +7,64 @@ module Faker
       NONE = 'none'
 
       def height(legacy_amount = NOT_GIVEN, amount: rand(10))
-        if legacy_amount != NOT_GIVEN
-          warn_with_uplevel 'Passing `amount` with the 1st argument of `Measurement.height` is deprecated. Use keyword argument like `Measurement.height(amount: ...)` instead.', uplevel: 1
-          amount = legacy_amount
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :amount if legacy_amount != NOT_GIVEN
         end
 
         define_measurement_locale(amount, 'height')
       end
 
       def length(legacy_amount = NOT_GIVEN, amount: rand(10))
-        if legacy_amount != NOT_GIVEN
-          warn_with_uplevel 'Passing `amount` with the 1st argument of `Measurement.length` is deprecated. Use keyword argument like `Measurement.length(amount: ...)` instead.', uplevel: 1
-          amount = legacy_amount
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :amount if legacy_amount != NOT_GIVEN
         end
 
         define_measurement_locale(amount, 'length')
       end
 
       def volume(legacy_amount = NOT_GIVEN, amount: rand(10))
-        if legacy_amount != NOT_GIVEN
-          warn_with_uplevel 'Passing `amount` with the 1st argument of `Measurement.volume` is deprecated. Use keyword argument like `Measurement.volume(amount: ...)` instead.', uplevel: 1
-          amount = legacy_amount
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :amount if legacy_amount != NOT_GIVEN
         end
 
         define_measurement_locale(amount, 'volume')
       end
 
       def weight(legacy_amount = NOT_GIVEN, amount: rand(10))
-        if legacy_amount != NOT_GIVEN
-          warn_with_uplevel 'Passing `amount` with the 1st argument of `Measurement.weight` is deprecated. Use keyword argument like `Measurement.weight(amount: ...)` instead.', uplevel: 1
-          amount = legacy_amount
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :amount if legacy_amount != NOT_GIVEN
         end
 
         define_measurement_locale(amount, 'weight')
       end
 
       def metric_height(legacy_amount = NOT_GIVEN, amount: rand(10))
-        if legacy_amount != NOT_GIVEN
-          warn_with_uplevel 'Passing `amount` with the 1st argument of `Measurement.metric_height` is deprecated. Use keyword argument like `Measurement.metric_height(amount: ...)` instead.', uplevel: 1
-          amount = legacy_amount
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :amount if legacy_amount != NOT_GIVEN
         end
 
         define_measurement_locale(amount, 'metric_height')
       end
 
       def metric_length(legacy_amount = NOT_GIVEN, amount: rand(10))
-        if legacy_amount != NOT_GIVEN
-          warn_with_uplevel 'Passing `amount` with the 1st argument of `Measurement.metric_length` is deprecated. Use keyword argument like `Measurement.metric_length(amount: ...)` instead.', uplevel: 1
-          amount = legacy_amount
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :amount if legacy_amount != NOT_GIVEN
         end
 
         define_measurement_locale(amount, 'metric_length')
       end
 
       def metric_volume(legacy_amount = NOT_GIVEN, amount: rand(10))
-        if legacy_amount != NOT_GIVEN
-          warn_with_uplevel 'Passing `amount` with the 1st argument of `Measurement.metric_volume` is deprecated. Use keyword argument like `Measurement.metric_volume(amount: ...)` instead.', uplevel: 1
-          amount = legacy_amount
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :amount if legacy_amount != NOT_GIVEN
         end
 
         define_measurement_locale(amount, 'metric_volume')
       end
 
       def metric_weight(legacy_amount = NOT_GIVEN, amount: rand(10))
-        if legacy_amount != NOT_GIVEN
-          warn_with_uplevel 'Passing `amount` with the 1st argument of `Measurement.metric_weight` is deprecated. Use keyword argument like `Measurement.metric_weight(amount: ...)` instead.', uplevel: 1
-          amount = legacy_amount
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :amount if legacy_amount != NOT_GIVEN
         end
 
         define_measurement_locale(amount, 'metric_weight')

data/lib/faker/default/military.rb

@@ -3,22 +3,67 @@
 module Faker
   class Military < Base
     class << self
+      ##
+      # Produces a rank in the U.S. Army.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Military.army_rank #=> "Staff Sergeant"
+      #
+      # @faker.version 1.9.0
       def army_rank
         fetch('military.army_rank')
       end
 
+      ##
+      # Produces a rank in the U.S. Marines.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Military.marines_rank #=> "Gunnery Sergeant"
+      #
+      # @faker.version 1.9.0
       def marines_rank
         fetch('military.marines_rank')
       end
 
+      ##
+      # Produces a rank in the U.S. Navy.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Military.navy_rank #=> "Seaman"
+      #
+      # @faker.version 1.9.0
       def navy_rank
         fetch('military.navy_rank')
       end
 
+      ##
+      # Produces a rank in the U.S. Air Force.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Military.air_force_rank #=> "Captain"
+      #
+      # @faker.version 1.9.0
       def air_force_rank
         fetch('military.air_force_rank')
       end
 
+      ##
+      # Produces a U.S. Department of Defense Paygrade.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Military.dod_paygrade #=> "E-6"
+      #
+      # @faker.version 1.9.0
       def dod_paygrade
         fetch('military.dod_paygrade')
       end

data/lib/faker/default/name.rb

@@ -47,9 +47,8 @@ module Faker
       end
 
       def initials(legacy_number = NOT_GIVEN, number: 3)
-        if legacy_number != NOT_GIVEN
-          warn_with_uplevel 'Passing `number` with the 1st argument of `Name.initials` is deprecated. Use keyword argument like `Name.initials(number: ...)` instead.', uplevel: 1
-          number = legacy_number
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :number if legacy_number != NOT_GIVEN
         end
 
         (0...number).map { rand(65..90).chr }.join

data/lib/faker/default/nation.rb

@@ -4,27 +4,70 @@ module Faker
   class Nation < Base
     flexible :nation
     class << self
-      # Fetch random nationality
+      ##
+      # Produces a random nationality.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Nation.nationality #=> "Nepalese"
+      #
+      # @faker.version 1.9.0
       def nationality
         fetch('nation.nationality')
       end
 
-      # Fetch random national flag emoji
+      # rubocop:disable Style/AsciiComments
+
+      ##
+      # Produces a random national flag emoji.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Nation.flag #=> "🇫🇮"
+      #
+      # @faker.version 1.9.0
       def flag
         sample(translate('faker.nation.flag')).pack('C*').force_encoding('utf-8')
       end
+      # rubocop:enable Style/AsciiComments
 
-      # Fetch random language
+      ##
+      # Produces a random national language.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Nation.language #=> "Nepali"
+      #
+      # @faker.version 1.9.0
       def language
         fetch('nation.language')
       end
 
-      # Fetch random capital city
+      ##
+      # Produces a random capital city.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Nation.capital_city #=> "Kathmandu"
+      #
+      # @faker.version 1.9.0
       def capital_city
         fetch('nation.capital_city')
       end
 
-      # Fetch random natinal sport
+      ##
+      # Produces a random national sport.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Nation.national_sport #=> "dandi biyo"
+      #
+      # @faker.version 1.9.0
       def national_sport
         fetch('team.sport')
       end

data/lib/faker/default/nato_phonetic_alphabet.rb

@@ -3,6 +3,15 @@
 module Faker
   class NatoPhoneticAlphabet < Base
     class << self
+      ##
+      # Produces a code word from the NATO phonetic alphabet.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::NatoPhoneticAlphabet.code_word #=> "Hotel"
+      #
+      # @faker.version 1.9.0
       def code_word
         fetch('nato_phonetic_alphabet.code_word')
       end

data/lib/faker/default/nhs.rb

@@ -16,9 +16,8 @@ module Faker
       end
 
       def check_digit(legacy_number = NOT_GIVEN, number: 0)
-        if legacy_number != NOT_GIVEN
-          warn_with_uplevel 'Passing `number` with the 1st argument of `NationalHealthService.check_digit` is deprecated. Use keyword argument like `NationalHealthService.check_digit(number: ...)` instead.', uplevel: 1
-          number = legacy_number
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :number if legacy_number != NOT_GIVEN
         end
 
         sum = 0

data/lib/faker/default/number.rb

@@ -3,32 +3,59 @@
 module Faker
   class Number < Base
     class << self
+      ##
+      # Produce a random number.
+      #
+      # @param digits [Integer] Number of digits that the generated number should have.
+      # @return [Integer]
+      #
+      # @example
+      #   Faker::Number.number(digits: 10) #=> 1968353479
+      #
+      # @faker.version 1.0.0
       def number(legacy_digits = NOT_GIVEN, digits: 10)
-        if legacy_digits != NOT_GIVEN
-          warn_with_uplevel 'Passing `digits` with the 1st argument of `Number.number` is deprecated. Use keyword argument like `Number.number(digits: ...)` instead.', uplevel: 1
-          digits = legacy_digits
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :digits if legacy_digits != NOT_GIVEN
         end
 
         return if digits < 1
-        return 0 if digits == 1
+        return rand(0..9).round if digits == 1
 
         # Ensure the first digit is not zero
         ([non_zero_digit] + generate(digits - 1)).join.to_i
       end
 
+      ##
+      # Produce a random number with a leading zero.
+      #
+      # @param digits [Integer] Number of digits that the generated number should have.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Number.leading_zero_number(digits: 10) #=> "0669336915"
+      #
+      # @faker.version 1.0.0
       def leading_zero_number(legacy_digits = NOT_GIVEN, digits: 10)
-        if legacy_digits != NOT_GIVEN
-          warn_with_uplevel 'Passing `digits` with the 1st argument of `Number.leading_zero_number` is deprecated. Use keyword argument like `Number.leading_zero_number(digits: ...)` instead.', uplevel: 1
-          digits = legacy_digits
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :digits if legacy_digits != NOT_GIVEN
         end
 
         '0' + (2..digits).collect { digit }.join
       end
 
+      ##
+      # Produce a number with a number of digits, preserves leading zeroes.
+      #
+      # @param digits [Integer] Number of digits that the generated number should have.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Number.decimal_part(digits: 2) #=> "09"
+      #
+      # @faker.version 1.0.0
       def decimal_part(legacy_digits = NOT_GIVEN, digits: 10)
-        if legacy_digits != NOT_GIVEN
-          warn_with_uplevel 'Passing `digits` with the 1st argument of `Number.decimal_part` is deprecated. Use keyword argument like `Number.decimal_part(digits: ...)` instead.', uplevel: 1
-          digits = legacy_digits
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :digits if legacy_digits != NOT_GIVEN
         end
 
         num = ''
@@ -39,14 +66,22 @@ module Faker
         leading_zero_number(digits: digits) + num.to_s
       end
 
+      ##
+      # Produces a float.
+      #
+      # @param l_digits [Integer] Number of digits that the generated decimal should have to the left of the decimal point.
+      # @param r_digits [Integer] Number of digits that the generated decimal should have to the right of the decimal point.
+      # @return [Float]
+      #
+      # @example
+      #   Faker::Number.decimal(l_digits: 2) #=> 11.88
+      #   Faker::Number.decimal(l_digits: 3, r_digits: 3) #=> 181.843
+      #
+      # @faker.version 1.0.0
       def decimal(legacy_l_digits = NOT_GIVEN, legacy_r_digits = NOT_GIVEN, l_digits: 5, r_digits: 2)
-        if legacy_l_digits != NOT_GIVEN
-          warn_with_uplevel 'Passing `l_digits` with the 1st argument of `Number.decimal` is deprecated. Use keyword argument like `Number.decimal(l_digits: ...)` instead.', uplevel: 1
-          l_digits = legacy_l_digits
-        end
-        if legacy_r_digits != NOT_GIVEN
-          warn_with_uplevel 'Passing `r_digits` with the 2nd argument of `Number.decimal` is deprecated. Use keyword argument like `Number.decimal(r_digits: ...)` instead.', uplevel: 1
-          r_digits = legacy_r_digits
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :l_digits if legacy_l_digits != NOT_GIVEN
+          keywords << :r_digits if legacy_r_digits != NOT_GIVEN
         end
 
         l_d = number(digits: l_digits)
@@ -60,18 +95,45 @@ module Faker
         "#{l_d}.#{r_d}".to_f
       end
 
+      ##
+      # Produces a non-zero single-digit integer.
+      #
+      # @return [Integer]
+      #
+      # @example
+      #   Faker::Number.non_zero_digit #=> 8
+      #
+      # @faker.version 1.0.0
       def non_zero_digit
         rand(1..9)
       end
 
+      ##
+      # Produces a single-digit integer.
+      #
+      # @return [Integer]
+      #
+      # @example
+      #   Faker::Number.digit #=> 1
+      #
+      # @faker.version 1.0.0
       def digit
         rand(10)
       end
 
+      ##
+      # Produces a number in hexadecimal format.
+      #
+      # @param digits [Integer] Number of digits in the he
+      # @return [String]
+      #
+      # @example
+      #   Faker::Number.hexadecimal(digits: 3) #=> "e74"
+      #
+      # @faker.version 1.0.0
       def hexadecimal(legacy_digits = NOT_GIVEN, digits: 6)
-        if legacy_digits != NOT_GIVEN
-          warn_with_uplevel 'Passing `digits` with the 1st argument of `Number.hexadecimal` is deprecated. Use keyword argument like `Number.hexadecimal(digits: ...)` instead.', uplevel: 1
-          digits = legacy_digits
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :digits if legacy_digits != NOT_GIVEN
         end
 
         hex = ''
@@ -79,14 +141,21 @@ module Faker
         hex
       end
 
+      ##
+      # Produces a float given a mean and standard deviation.
+      #
+      # @param mean [Integer]
+      # @param standard_deviation [Integer, Float]
+      # @return [Float]
+      #
+      # @example
+      #   Faker::Number.normal(mean: 50, standard_deviation: 3.5) #=> 47.14669604069156
+      #
+      # @faker.version 1.0.0
       def normal(legacy_mean = NOT_GIVEN, legacy_standard_deviation = NOT_GIVEN, mean: 1, standard_deviation: 1)
-        if legacy_mean != NOT_GIVEN
-          warn_with_uplevel 'Passing `mean` with the 1st argument of `Number.normal` is deprecated. Use keyword argument like `Number.normal(mean: ...)` instead.', uplevel: 1
-          mean = legacy_mean
-        end
-        if legacy_standard_deviation != NOT_GIVEN
-          warn_with_uplevel 'Passing `standard_deviation` with the 2nd argument of `Number.normal` is deprecated. Use keyword argument like `Number.normal(standard_deviation: ...)` instead.', uplevel: 1
-          standard_deviation = legacy_standard_deviation
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :mean if legacy_mean != NOT_GIVEN
+          keywords << :standard_deviation if legacy_standard_deviation != NOT_GIVEN
         end
 
         theta = 2 * Math::PI * rand
@@ -95,36 +164,59 @@ module Faker
         mean + scale * Math.cos(theta)
       end
 
+      ##
+      # Produces a number between two provided values. Boundaries are inclusive.
+      #
+      # @param from [Integer] The lowest number to include.
+      # @param to [Integer] The highest number to include.
+      # @return [Integer]
+      #
+      # @example
+      #   Faker::Number.between(from: 1, to: 10) #=> 7
+      #
+      # @faker.version 1.0.0
       def between(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from: 1.00, to: 5000.00)
-        if legacy_from != NOT_GIVEN
-          warn_with_uplevel 'Passing `from` with the 1st argument of `Number.between` is deprecated. Use keyword argument like `Number.between(from: ...)` instead.', uplevel: 1
-          from = legacy_from
-        end
-        if legacy_to != NOT_GIVEN
-          warn_with_uplevel 'Passing `to` with the 2nd argument of `Number.between` is deprecated. Use keyword argument like `Number.between(to: ...)` instead.', uplevel: 1
-          to = legacy_to
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :from if legacy_from != NOT_GIVEN
+          keywords << :to if legacy_to != NOT_GIVEN
         end
 
         Faker::Base.rand_in_range(from, to)
       end
 
+      ##
+      # Produces a number within two provided values. Boundaries are inclusive or exclusive depending on the range passed.
+      #
+      # @param range [Range] The range from which to generate a number.
+      # @return [Integer]
+      #
+      # @example
+      #   Faker::Number.within(range: 1..10) #=> 7
+      #
+      # @faker.version 1.0.0
       def within(legacy_range = NOT_GIVEN, range: 1.00..5000.00)
-        if legacy_range != NOT_GIVEN
-          warn_with_uplevel 'Passing `range` with the 1st argument of `Number.within` is deprecated. Use keyword argument like `Number.within(range: ...)` instead.', uplevel: 1
-          range = legacy_range
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :range if legacy_range != NOT_GIVEN
         end
 
         between(from: range.min, to: range.max)
       end
 
+      ##
+      # Produces a positive float.
+      #
+      # @param from [Integer] The lower boundary.
+      # @param to [Integer] The higher boundary.
+      # @return [Float]
+      #
+      # @example
+      #   Faker::Number.positive #=> 235.59238499107653
+      #
+      # @faker.version 1.0.0
       def positive(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from: 1.00, to: 5000.00)
-        if legacy_from != NOT_GIVEN
-          warn_with_uplevel 'Passing `from` with the 1st argument of `Number.positive` is deprecated. Use keyword argument like `Number.positive(from: ...)` instead.', uplevel: 1
-          from = legacy_from
-        end
-        if legacy_to != NOT_GIVEN
-          warn_with_uplevel 'Passing `to` with the 2nd argument of `Number.positive` is deprecated. Use keyword argument like `Number.positive(to: ...)` instead.', uplevel: 1
-          to = legacy_to
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :from if legacy_from != NOT_GIVEN
+          keywords << :to if legacy_to != NOT_GIVEN
         end
 
         random_number = between(from: from, to: to)
@@ -132,14 +224,21 @@ module Faker
         greater_than_zero(random_number)
       end
 
+      ##
+      # Produces a negative float.
+      #
+      # @param from [Integer] The lower boundary.
+      # @param to [Integer] The higher boundary.
+      # @return [Float]
+      #
+      # @example
+      #   Faker::Number.negative #=> -4480.042585669558
+      #
+      # @faker.version 1.0.0
       def negative(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from: -5000.00, to: -1.00)
-        if legacy_from != NOT_GIVEN
-          warn_with_uplevel 'Passing `from` with the 1st argument of `Number.negative` is deprecated. Use keyword argument like `Number.negative(from: ...)` instead.', uplevel: 1
-          from = legacy_from
-        end
-        if legacy_to != NOT_GIVEN
-          warn_with_uplevel 'Passing `to` with the 2nd argument of `Number.negative` is deprecated. Use keyword argument like `Number.negative(to: ...)` instead.', uplevel: 1
-          to = legacy_to
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :from if legacy_from != NOT_GIVEN
+          keywords << :to if legacy_to != NOT_GIVEN
         end
 
         random_number = between(from: from, to: to)