faker 2.2.0 → 2.5.0

data/lib/faker/creature/animal.rb

@@ -4,6 +4,15 @@ module Faker
   class Creature
     class Animal < Base
       class << self
+        ##
+        # Produces a random animal name
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Animal.name #=> "fly"
+        #
+        # @faker.version 1.9.2
         def name
           fetch('creature.animal.name')
         end

data/lib/faker/creature/cat.rb

@@ -6,14 +6,41 @@ module Faker
       flexible :cat
 
       class << self
+        ##
+        # Produces a random name for a cat
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Cat.name #=> "Felix"
+        #
+        # @faker.version 1.9.2
         def name
           fetch('creature.cat.name')
         end
 
+        ##
+        # Produces a random cat breed
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Cat.breed #=> "Scottish Fold"
+        #
+        # @faker.version 1.9.2
         def breed
           fetch('creature.cat.breed')
         end
 
+        ##
+        # Produces a random cat breed registry
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Cat.registry #=> "Fancy Southern Africa Cat Council"
+        #
+        # @faker.version 1.9.2
         def registry
           fetch('creature.cat.registry')
         end

data/lib/faker/creature/dog.rb

@@ -6,34 +6,106 @@ module Faker
       flexible :dog
 
       class << self
+        ##
+        # Produces a random name for a dog
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Dog.name #=> "Spike"
+        #
+        # @faker.version 1.9.2
         def name
           fetch('creature.dog.name')
         end
 
+        ##
+        # Produces a random dog breed
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Dog.breed #=> "Yorkshire Terrier"
+        #
+        # @faker.version 1.9.2
         def breed
           fetch('creature.dog.breed')
         end
 
+        ##
+        # Produces a random sound made by a dog
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Dog.sound #=> "woof woof"
+        #
+        # @faker.version 1.9.2
         def sound
           fetch('creature.dog.sound')
         end
 
+        ##
+        # Produces a random dog meme phrase
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Dog.meme_phrase #=> "smol pupperino"
+        #
+        # @faker.version 1.9.2
         def meme_phrase
           fetch('creature.dog.meme_phrase')
         end
 
+        ##
+        # Produces a random dog age
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Dog.age #=> "puppy"
+        #
+        # @faker.version 1.9.2
         def age
           fetch('creature.dog.age')
         end
 
+        ##
+        # Produces a random gender
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Dog.gender #=> "Female"
+        #
+        # @faker.version 1.9.2
         def gender
           Faker::Gender.binary_type
         end
 
+        ##
+        # Produces a random coat length
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Dog.coat_length #=> "short"
+        #
+        # @faker.version 1.9.2
         def coat_length
           fetch('creature.dog.coat_length')
         end
 
+        ##
+        # Produces a random size of a dog
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Dog.size #=> "small"
+        #
+        # @faker.version 1.9.2
         def size
           fetch('creature.dog.size')
         end

data/lib/faker/creature/horse.rb

@@ -6,10 +6,28 @@ module Faker
       flexible :horse
 
       class << self
+        ##
+        # Produces a random name for a horse
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Horse.name #=> "Noir"
+        #
+        # @faker.version 1.9.2
         def name
           fetch('creature.horse.name')
         end
 
+        ##
+        # Produces a random horse breed
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Horse.breed #=> "Spanish Barb see Barb Horse"
+        #
+        # @faker.version 1.9.2
         def breed
           fetch('creature.horse.breed')
         end

data/lib/faker/default/address.rb

@@ -6,9 +6,8 @@ module Faker
 
     class << self
       def city(legacy_options = NOT_GIVEN, options: {})
-        if legacy_options != NOT_GIVEN
-          warn_with_uplevel 'Passing `options` with the 1st argument of `Address.city` is deprecated. Use keyword argument like `Address.city(options: ...)` instead.', uplevel: 1
-          options = legacy_options
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :options if legacy_options != NOT_GIVEN
         end
 
         parse(options[:with_state] ? 'address.city_with_state' : 'address.city')
@@ -19,9 +18,8 @@ module Faker
       end
 
       def street_address(legacy_include_secondary = NOT_GIVEN, include_secondary: false)
-        if legacy_include_secondary != NOT_GIVEN
-          warn_with_uplevel 'Passing `include_secondary` with the 1st argument of `Address.street_address` is deprecated. Use keyword argument like `Address.street_address(include_secondary: ...)` instead.', uplevel: 1
-          include_secondary = legacy_include_secondary
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :include_secondary if legacy_include_secondary != NOT_GIVEN
         end
 
         numerify(parse('address.street_address') + (include_secondary ? ' ' + secondary_address : ''))
@@ -40,9 +38,8 @@ module Faker
       end
 
       def zip_code(legacy_state_abbreviation = NOT_GIVEN, state_abbreviation: '')
-        if legacy_state_abbreviation != NOT_GIVEN
-          warn_with_uplevel 'Passing `state_abbreviation` with the 1st argument of `Address.zip_code` is deprecated. Use keyword argument like `Address.zip_code(state_abbreviation: ...)` instead.', uplevel: 1
-          state_abbreviation = legacy_state_abbreviation
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :state_abbreviation if legacy_state_abbreviation != NOT_GIVEN
         end
 
         if state_abbreviation.empty?
@@ -87,18 +84,16 @@ module Faker
       end
 
       def country_by_code(legacy_code = NOT_GIVEN, code: 'US')
-        if legacy_code != NOT_GIVEN
-          warn_with_uplevel 'Passing `code` with the 1st argument of `Address.country_by_code` is deprecated. Use keyword argument like `Address.country_by_code(code: ...)` instead.', uplevel: 1
-          code = legacy_code
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :code if legacy_code != NOT_GIVEN
         end
 
         fetch('address.country_by_code.' + code)
       end
 
       def country_name_to_code(legacy_name = NOT_GIVEN, name: 'united_states')
-        if legacy_name != NOT_GIVEN
-          warn_with_uplevel 'Passing `name` with the 1st argument of `Address.country_name_to_code` is deprecated. Use keyword argument like `Address.country_name_to_code(name: ...)` instead.', uplevel: 1
-          name = legacy_name
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :name if legacy_name != NOT_GIVEN
         end
 
         fetch('address.country_by_name.' + name)

data/lib/faker/default/alphanumeric.rb

@@ -2,13 +2,26 @@
 
 module Faker
   class Alphanumeric < Base
+    ##
+    # List of characters allowed for alphanumeric strings
+    # @private
     ALPHANUMS = LLetters + Numbers
 
     class << self
+      ##
+      # Produces a random string of alphabetic characters (no digits)
+      #
+      # @param number [Integer] The length of the string to generate
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Alphanumeric.alpha(number: 10) #=> "zlvubkrwga"
+      #
+      # @faker.version 1.9.2
       def alpha(legacy_number = NOT_GIVEN, number: 32)
-        if legacy_number != NOT_GIVEN
-          warn_with_uplevel 'Passing `number` with the 1st argument of `Alphanumeric.alpha` is deprecated. Use keyword argument like `Alphanumeric.alpha(number: ...)` instead.', uplevel: 1
-          number = legacy_number
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :number if legacy_number != NOT_GIVEN
         end
         char_count = resolve(number)
         return '' if char_count.to_i < 1
@@ -19,34 +32,32 @@ module Faker
       ##
       # Produces a random string of alphanumeric characters
       #
-      # @param [Integer] number
-      # @param [Integer] min_alpha
-      # @param [Integer] min_numeric
+      # @param number [Integer] The number of characters to generate
+      # @param min_alpha [Integer] The minimum number of alphabetic to add to the string
+      # @param min_numeric [Integer] The minimum number of numbers to add to the string
       #
       # @return [String]
       #
-      # @example Faker::Alphanumeric.alphanumeric(number: 10) #=> "3yfq2phxtb"
-      # @example Faker::Alphanumeric.alphanumeric(number: 10, min_alpha: 3) #=> "3yfq2phxtb"
-      # @example Faker::Alphanumeric.alphanumeric(number: 10, min_alpha: 3, min_numeric: 3) #=> "3yfq2phx8b"
+      # @example
+      #   Faker::Alphanumeric.alphanumeric(number: 10) #=> "3yfq2phxtb"
+      # @example
+      #   Faker::Alphanumeric.alphanumeric(number: 10, min_alpha: 3) #=> "3yfq2phxtb"
+      # @example
+      #   Faker::Alphanumeric.alphanumeric(number: 10, min_alpha: 3, min_numeric: 3) #=> "3yfq2phx8b"
       #
       # @faker.version 2.1.3
       def alphanumeric(legacy_number = NOT_GIVEN, number: 32, min_alpha: 0, min_numeric: 0)
-        if legacy_number != NOT_GIVEN
-          warn_with_uplevel 'Passing `number` with the 1st argument of `Alphanumeric.alphanumeric` is deprecated. Use keyword argument like `Alphanumeric.alphanumeric(number: ...)` instead.', uplevel: 1
-          number = legacy_number
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :number if legacy_number != NOT_GIVEN
         end
         char_count = resolve(number)
         return '' if char_count.to_i < 1
         raise ArgumentError, 'min_alpha must be greater than or equal to 0' if min_alpha&.negative?
         raise ArgumentError, 'min_numeric must be greater than or equal to 0' if min_numeric&.negative?
 
-        if min_alpha.zero? && min_numeric.zero?
-          return Array.new(char_count) { sample(ALPHANUMS) }.join
-        end
+        return Array.new(char_count) { sample(ALPHANUMS) }.join if min_alpha.zero? && min_numeric.zero?
 
-        if min_alpha + min_numeric > char_count
-          raise ArgumentError, 'min_alpha + min_numeric must be <= number'
-        end
+        raise ArgumentError, 'min_alpha + min_numeric must be <= number' if min_alpha + min_numeric > char_count
 
         random_count = char_count - min_alpha - min_numeric
 

data/lib/faker/default/app.rb

@@ -3,32 +3,71 @@
 module Faker
   class App < Base
     class << self
+      ##
+      # Produces an app name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::App.name #=> "Treeflex"
+      #
+      # @faker.version 1.4.3
       def name
         fetch('app.name')
       end
 
+      ##
+      # Produces a version string.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::App.version #=> "1.85"
+      #
+      # @faker.version 1.4.3
       def version
         parse('app.version')
       end
 
+      ##
+      # Produces the name of an app's author.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::App.author #=> "Daphne Swift"
+      #
+      # @faker.version 1.4.3
       def author
         parse('app.author')
       end
 
       # rubocop:disable Metrics/ParameterLists
+
+      ##
+      # Produces a String representing a semantic version identifier.
+      #
+      # @param major [Integer, Range] An integer to use or a range to pick the integer from.
+      # @param minor [Integer, Range] An integer to use or a range to pick the integer from.
+      # @param patch [Integer, Range] An integer to use or a range to pick the integer from.
+      # @return [String]
+      #
+      # @example
+      #   Faker::App.semantic_version #=> "3.2.5"
+      # @example
+      #   Faker::App.semantic_version(major: 42) #=> "42.5.2"
+      # @example
+      #   Faker::App.semantic_version(minor: 100..101) #=> "42.100.4"
+      # @example
+      #   Faker::App.semantic_version(patch: 5..6) #=> "7.2.6"
+      #
+      # @faker.version 1.4.3
       def semantic_version(legacy_major = NOT_GIVEN, legacy_minor = NOT_GIVEN, legacy_patch = NOT_GIVEN, major: 0..9, minor: 0..9, patch: 1..9)
         # rubocop:enable Metrics/ParameterLists
-        if legacy_major != NOT_GIVEN
-          warn_with_uplevel 'Passing `major` with the 1st argument of `App.semantic_version` is deprecated. Use keyword argument like `App.semantic_version(major: ...)` instead.', uplevel: 1
-          major = legacy_major
-        end
-        if legacy_minor != NOT_GIVEN
-          warn_with_uplevel 'Passing `minor` with the 2nd argument of `App.semantic_version` is deprecated. Use keyword argument like `App.semantic_version(minor: ...)` instead.', uplevel: 1
-          minor = legacy_minor
-        end
-        if legacy_patch != NOT_GIVEN
-          warn_with_uplevel 'Passing `patch` with the 3rd argument of `App.semantic_version` is deprecated. Use keyword argument like `App.semantic_version(patch: ...)` instead.', uplevel: 1
-          patch = legacy_patch
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :major if legacy_major != NOT_GIVEN
+          keywords << :minor if legacy_minor != NOT_GIVEN
+          keywords << :patch if legacy_patch != NOT_GIVEN
         end
 
         [major, minor, patch].map { |chunk| sample(Array(chunk)) }.join('.')

data/lib/faker/default/appliance.rb

@@ -3,10 +3,28 @@
 module Faker
   class Appliance < Base
     class << self
+      ##
+      # Produces the name of an appliance brand.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Appliance.brand #=> "Bosch"
+      #
+      # @faker.version 1.9.0
       def brand
         fetch('appliance.brand')
       end
 
+      ##
+      # Produces the name of a type of appliance equipment.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Appliance.equipment #=> "Appliance plug"
+      #
+      # @faker.version 1.9.0
       def equipment
         fetch('appliance.equipment')
       end

data/lib/faker/default/artist.rb

@@ -3,6 +3,15 @@
 module Faker
   class Artist < Base
     class << self
+      ##
+      # Produces the name of an artist.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Artist.name #=> "Michelangelo"
+      #
+      # @faker.version 1.8.8
       def name
         fetch('artist.names')
       end