faker 2.2.0 → 3.2.2

data/lib/faker/default/markdown.rb

@@ -3,19 +3,46 @@
 module Faker
   class Markdown < Base
     class << self
+      ##
+      # Produces a random header format.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Markdown.headers #=> "##### Autem"
+      #
+      # @faker.version 1.8.0
       def headers
         "#{fetch('markdown.headers')} #{Lorem.word.capitalize}"
       end
 
+      ##
+      # Produces a random emphasis formatting on a random word in two sentences.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Markdown.emphasis #=> "_Incidunt atque quis repellat id impedit.  Quas numquam quod incidunt dicta non. Blanditiis delectus laudantium atque reiciendis qui._"
+      #
+      # @faker.version 1.8.0
       def emphasis
         paragraph = Faker::Lorem.paragraph(sentence_count: 3)
-        words = paragraph.split(' ')
+        words = paragraph.split
         position = rand(0..words.length - 1)
         formatting = fetch('markdown.emphasis')
         words[position] = "#{formatting}#{words[position]}#{formatting}"
         words.join(' ')
       end
 
+      ##
+      # Produces a random ordered list of items between 1 and 10 randomly.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Markdown.ordered_list #=> "1. Qui reiciendis non consequatur atque.\n2. Quo doloremque veritatis tempora aut.\n3. Aspernatur.\n4. Ea ab.\n5. Qui.\n6. Sit pariatur nemo eveniet.\n7. Molestiae aut.\n8. Nihil molestias iure placeat.\n9. Dolore autem quisquam."
+      #
+      # @faker.version 1.8.0
       def ordered_list
         number = rand(1..10)
 
@@ -23,9 +50,18 @@ module Faker
         number.times do |i|
           result << "#{i}. #{Faker::Lorem.sentence(word_count: 1)} \n"
         end
-        result.join('')
+        result.join
       end
 
+      ##
+      # Produces a random unordered list of items between 1 and 10 randomly.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Markdown.unordered_list #=> "* Voluptatum aliquid tempora molestiae facilis non sed.\n* Nostrum omnis iste impedit voluptatum dolor.\n* Esse quidem et facere."
+      #
+      # @faker.version 1.8.0
       def unordered_list
         number = rand(1..10)
 
@@ -33,17 +69,44 @@ module Faker
         number.times do |_i|
           result << "* #{Faker::Lorem.sentence(word_count: 1)} \n"
         end
-        result.join('')
+        result.join
       end
 
+      ##
+      # Produces a random inline code snippet between two sentences.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Markdown.inline_code #=> "Aut eos quis suscipit. `Dignissimos voluptatem expedita qui.` Quo doloremque veritatis tempora aut."
+      #
+      # @faker.version 1.8.0
       def inline_code
         "`#{Faker::Lorem.sentence(word_count: 1)}`"
       end
 
+      ##
+      # Produces a random code block formatted in Ruby.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Markdown.block_code #=> "```ruby\nEos quasi qui.\n```"
+      #
+      # @faker.version 1.8.0
       def block_code
         "```ruby\n#{Lorem.sentence(word_count: 1)}\n```"
       end
 
+      ##
+      # Produces a random 3x4 table with a row of headings, a row of hyphens and two rows of data
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Markdown.table #=> "ad | similique | voluptatem\n---- | ---- | ----\ncorrupti | est | rerum\nmolestiae | quidem | et"
+      #
+      # @faker.version 1.8.0
       def table
         table = []
         3.times do
@@ -53,22 +116,41 @@ module Faker
         table.join("\n")
       end
 
+      ##
+      # Produces a random method from the methods above, excluding the methods listed in the arguments.
+      #
+      # @overload random(methods)
+      #   @param methods [Symbol] Specify which methods to exclude.
+      #
+      # @return [String, Array<String>]
+      #
+      # @example
+      #   Faker::Markdown.random #=> returns output from a single method outlined above
+      #   Faker::Markdown.random("table") #=> returns output from any single method outlined above except for "table"
+      #   Faker::Markdown.random("ordered_list", "unordered_list") #=> returns output from any single method outlined above except for either ordered_list and unordered_list
+      #
+      # @faker.version 1.8.0
       def random(*args)
         method_list = available_methods
         args&.each { |ex| method_list.delete_if { |meth| meth == ex.to_sym } }
-        send(method_list[rand(0..method_list.length - 1)])
+        send(method_list[Faker::Config.random.rand(0..method_list.length - 1)])
       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
-        end
-
+      ##
+      # Produces a simulated blog-esque text-heavy block in markdown
+      #
+      # Keyword arguments: sentences, repeat
+      # @param sentences [Integer] Specifies how many sentences make a text block.
+      # @param repeat [Integer] Specifies how many times the text block repeats.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Markdown.sandwich #=> returns newline separated content of 1 header, 1 default lorem paragraph, and 1 random markdown element
+      #   Faker::Markdown.sandwich(sentences: 5) #=> returns newline separated content of 1 header, 1 5-sentence lorem paragraph, and 1 random markdown element
+      #   Faker::Markdown.sandwich(sentences: 6, repeat: 3) #=> returns newline separated content of 1 header, and then 3 sections consisting of, here, 1 6-sentence lorem paragraph and 1 random markdown element. The random markdown element is chosen at random in each iteration of the paragraph-markdown pairing.
+      #
+      # @faker.version 1.8.0
+      def sandwich(sentences: 3, repeat: 1)
         text_block = []
         text_block << headers
         repeat.times do
@@ -81,7 +163,7 @@ module Faker
       private
 
       def available_methods
-        Markdown.public_methods(false) - Base.methods
+        (Markdown.public_methods(false) - Base.methods).sort
       end
     end
   end

data/lib/faker/default/marketing.rb

@@ -5,6 +5,15 @@ module Faker
     flexible :marketing
 
     class << self
+      ##
+      # Produces a few marketing buzzwords.
+      #
+      # @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

@@ -6,75 +6,125 @@ module Faker
       ALL = 'all'
       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
-        end
-
+      ##
+      # Produces a random height measurement.
+      #
+      # @param amount [Integer] Specifies 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(amount: rand(10))
         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
-        end
-
+      ##
+      # Produces a random length measurement.
+      #
+      # @param amount [Integer] Specifies 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(amount: rand(10))
         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
-        end
-
+      ##
+      # Produces a random volume measurement.
+      #
+      # @param amount [Integer] Specifies 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(amount: rand(10))
         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
-        end
-
+      ##
+      # Produces a random weight measurement.
+      #
+      # @param amount [Integer] Specifies 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(amount: rand(10))
         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
-        end
-
+      ##
+      # Produces a random metric height measurement.
+      #
+      # @param amount [Integer] Specifies 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(amount: rand(10))
         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
-        end
-
+      ##
+      # Produces a random metric length measurement.
+      #
+      # @param amount [Integer] Specifies 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(amount: rand(10))
         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
-        end
-
+      ##
+      # Produces a random metric volume measurement.
+      #
+      # @param amount [Integer] Specifies 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(amount: rand(10))
         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
-        end
-
+      ##
+      # Produces a random metric weight measurement.
+      #
+      # @param amount [Integer] Specifies 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(amount: rand(10))
         define_measurement_locale(amount, 'metric_weight')
       end
 
@@ -90,9 +140,10 @@ module Faker
 
       def define_measurement_locale(amount, locale)
         ensure_valid_amount(amount)
-        if amount == ALL
+        case amount
+        when ALL
           make_plural(fetch("measurement.#{locale}"))
-        elsif amount == NONE
+        when NONE
           fetch("measurement.#{locale}")
         else
           locale = check_for_plural(fetch("measurement.#{locale}"), amount)

data/lib/faker/default/military.rb

@@ -3,22 +3,93 @@
 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 rank in the U.S. Space Force.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Military.space_force_rank #=> "Senior Enlisted Advisor of the Space Force"
+      #
+      # @faker.version next
+      def space_force_rank
+        fetch('military.space_force_rank')
+      end
+
+      ##
+      # Produces a rank in the U.S. Coast Guard
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Military.coast_guard_rank #=> "Master Chief Petty Officer of the Coast Guard"
+      #
+      # @faker.version next
+      def coast_guard_rank
+        fetch('military.coast_guard_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/mountain.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Faker
+  class Mountain < Base
+    class << self
+      ##
+      # Produces a name of a mountain
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Mountain.name #=> "Mount Everest"
+      #
+      #  @faker.version next
+      def name
+        fetch('mountain.name')
+      end
+
+      ##
+      # Produces a name of a range
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Mountain.range #=> "Dhaulagiri Himalaya"
+      #
+      # @faker.version next
+      def range
+        fetch('mountain.range')
+      end
+    end
+  end
+end

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,37 +48,103 @@ 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
 
-      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
-        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(number: 3)
         (0...number).map { rand(65..90).chr }.join
       end
     end