faker 2.2.0 → 3.2.2

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

@@ -5,46 +5,115 @@ module Faker
     flexible :address
 
     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
-        end
-
+      ##
+      # Produces the name of a city.
+      #
+      # @param options [Hash]
+      # @option with_state [Boolean] Whether to include the state name in the output.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.city #=> "Imogeneborough"
+      #   Faker::Address.city(options: { with_state: true })
+      #     #=> "Northfort, California"
+      #
+      # @faker.version 0.3.0
+      def city(options: {})
         parse(options[:with_state] ? 'address.city_with_state' : 'address.city')
       end
 
+      ##
+      # Produces a street name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.street_name #=> "Larkin Fork"
+      #
+      # @faker.version 0.3.0
       def street_name
         parse('address.street_name')
       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
-        end
-
-        numerify(parse('address.street_address') + (include_secondary ? ' ' + secondary_address : ''))
+      ##
+      # Produces a street address.
+      #
+      # @param include_secondary [Boolean] Whether or not to include the secondary address.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.street_address #=> "282 Kevin Brook"
+      #
+      # @faker.version 0.3.0
+      def street_address(include_secondary: false)
+        numerify(parse('address.street_address') + (include_secondary ? " #{secondary_address}" : ''))
       end
 
+      ##
+      # Produces a secondary address.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.secondary_address #=> "Apt. 672"
+      #
+      # @faker.version 0.3.0
       def secondary_address
         bothify(fetch('address.secondary_address'))
       end
 
+      ##
+      # Produces a building number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.building_number #=> "7304"
+      #
+      # @faker.version 0.3.0
       def building_number
         bothify(fetch('address.building_number'))
       end
 
+      ##
+      # Produces the name of a community.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.community #=> "University Crossing"
+      #
+      # @faker.version 1.8.0
       def community
         parse('address.community')
       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
-        end
+      ##
+      #
+      # Produces a mail box number.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.mail_box #=> "PO Box 123"
+      #
+      # @faker.version 2.9.1
+      def mail_box
+        bothify(fetch('address.mail_box'))
+      end
 
+      ##
+      # Produces a Zip Code.
+      #
+      # @param state_abbreviation [String] an abbreviation for a state where the zip code should be located.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.zip_code #=> "58517"
+      #   Faker::Address.zip_code #=> "23285-4905"
+      #   Faker::Address.zip_code(state_abbreviation: 'CO') #=> "80011"
+      #
+      # @faker.version 0.3.0
+      def zip_code(state_abbreviation: '')
         if state_abbreviation.empty?
           letterified_string = letterify(fetch('address.postcode'))
           return numerify(letterified_string, leading_zero: true)
@@ -52,9 +121,18 @@ module Faker
 
         # provide a zip code that is valid for the state provided
         # see http://www.fincen.gov/forms/files/us_state_territory_zip_codes.pdf
-        bothify(fetch('address.postcode_by_state.' + state_abbreviation))
+        bothify(fetch("address.postcode_by_state.#{state_abbreviation}"))
       end
 
+      ##
+      # Produces the name of a time zone.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.time_zone #=> "Asia/Yakutsk"
+      #
+      # @faker.version 1.2.0
       def time_zone
         fetch('address.time_zone')
       end
@@ -62,67 +140,209 @@ module Faker
       alias zip zip_code
       alias postcode zip_code
 
+      ##
+      # Produces a street suffix.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.street_suffix #=> "Street"
+      #
+      # @faker.version 0.3.0
       def street_suffix
         fetch('address.street_suffix')
       end
 
+      ##
+      # Produces a city suffix.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.city_suffix #=> "fort"
+      #
+      # @faker.version 0.3.0
       def city_suffix
         fetch('address.city_suffix')
       end
 
+      ##
+      # Produces a city prefix.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.city_prefix #=> "Lake"
+      #
+      # @faker.version 0.3.0
       def city_prefix
         fetch('address.city_prefix')
       end
 
+      ##
+      # Produces a state abbreviation.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.state_abbr #=> "AP"
+      #
+      # @faker.version 0.3.0
       def state_abbr
         fetch('address.state_abbr')
       end
 
+      ##
+      # Produces the name of a state.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.state #=> "California"
+      #
+      # @faker.version 0.3.0
       def state
         fetch('address.state')
       end
 
+      ##
+      # Produces the name of a country.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.country #=> "French Guiana"
+      #
+      # @faker.version 0.3.0
       def country
         fetch('address.country')
       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
-        end
-
-        fetch('address.country_by_code.' + code)
+      ##
+      # Produces a country by ISO country code. See the
+      # [List of ISO 3166 country codes](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes)
+      # on Wikipedia for a full list.
+      #
+      # @param code [String] An ISO country code.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.country_by_code(code: 'NL') #=> "Netherlands"
+      #
+      # @faker.version 1.9.2
+      def country_by_code(code: 'US')
+        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
-        end
-
-        fetch('address.country_by_name.' + name)
+      ##
+      # Produces an ISO 3166 country code when given a country name.
+      #
+      # @param name [String] Country name in snake_case format.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.country_name_to_code(name: 'united_states') #=> "US"
+      #
+      # @faker.version 1.9.2
+      def country_name_to_code(name: 'united_states')
+        fetch("address.country_by_name.#{name}")
       end
 
+      ##
+      # Produces an ISO 3166 country code.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.country_code #=> "IT"
+      #
+      # @faker.version 1.4.0
       def country_code
         fetch('address.country_code')
       end
 
+      ##
+      # Produces a long (alpha-3) ISO 3166 country code.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.country_code_long #=> "ITA"
+      #
+      # @faker.version 0.3.0
       def country_code_long
         fetch('address.country_code_long')
       end
 
+      ##
+      # Produces a latitude.
+      #
+      # @return [Float]
+      #
+      # @example
+      #   Faker::Address.latitude #=> -58.17256227443719
+      #
+      # @faker.version 1.0.0
       def latitude
         ((rand * 180) - 90).to_f
       end
 
+      ##
+      # Produces a longitude.
+      #
+      # @return [Float]
+      #
+      # @example
+      #   Faker::Address.longitude #=> -156.65548382095133
+      #
+      # @faker.version 1.0.0
       def longitude
         ((rand * 360) - 180).to_f
       end
 
+      ##
+      # Produces a full address.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Address.full_address
+      #     #=> "282 Kevin Brook, Imogeneborough, CA 58517"
+      #
+      # @faker.version 0.3.0
       def full_address
         parse('address.full_address')
       end
+
+      ##
+      # Produces Address hash of required fields
+      #
+      # @return [Hash]
+      #
+      # @example
+      #   Faker::Address.full_address_as_hash(:longitude,
+      #                                       :latitude,
+      #                                       :country_name_to_code,
+      #                                       country_name_to_code: {name: 'united_states'})
+      #     #=> {:longitude=>-101.74428917174603, :latitude=>-37.40056749089944, :country_name_to_code=>"US"}
+      #
+      #  Faker::Address.full_address_as_hash(:full_address)
+      #     #=> {:full_address=>"87635 Rice Street, Lake Brentonton, OR 61896-5968"}
+      #
+      #  Faker::Address.full_address_as_hash(:city, :time_zone)
+      #     #=> {:city=>"East Faustina", :time_zone=>"America/Mexico_City"}
+      #
+      #  Faker::Address.full_address_as_hash(:street_address, street_address: {include_secondary: true})
+      #     #=> {:street_address=>"29423 Kenneth Causeway Suite 563"}
+      #
+      # @faker.version 2.13.0
+      def full_address_as_hash(*attrs, **attrs_params)
+        attrs.map!(&:to_sym)
+        attrs_params.transform_keys!(&:to_sym)
+        attrs.map do |attr|
+          { "#{attr}": attrs_params[attr] ? send(attr, **attrs_params[attr]) : send(attr) }
+        end.reduce({}, :merge)
+      end
     end
   end
 end

data/lib/faker/default/adjective.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Faker
+  class Adjective < Base
+    flexible :adjective
+
+    class << self
+      ##
+      # Produces a positive adjective.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Adjective.positive #=> "Kind"
+      #
+      # @faker.version next
+      def positive
+        fetch('adjective.positive')
+      end
+
+      ##
+      # Produces a negative adjective.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Adjective.negative #=> "Creepy"
+      #
+      # @faker.version next
+      def negative
+        fetch('adjective.negative')
+      end
+    end
+  end
+end

data/lib/faker/default/alphanumeric.rb

@@ -2,14 +2,24 @@
 
 module Faker
   class Alphanumeric < Base
+    ##
+    # List of characters allowed for alphanumeric strings
+    # @private
     ALPHANUMS = LLetters + Numbers
 
     class << self
-      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
-        end
+      ##
+      # 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(number: 32)
         char_count = resolve(number)
         return '' if char_count.to_i < 1
 
@@ -19,34 +29,29 @@ 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
-        end
+      def alphanumeric(number: 32, min_alpha: 0, min_numeric: 0)
         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/ancient.rb

@@ -3,18 +3,54 @@
 module Faker
   class Ancient < Base
     class << self
+      ##
+      # Produces a god from ancient mythology.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Ancient.god #=> "Zeus"
+      #
+      # @faker.version 1.7.0
       def god
         fetch('ancient.god')
       end
 
+      ##
+      # Produces a primordial from ancient mythology.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Ancient.primordial #=> "Gaia"
+      #
+      # @faker.version 1.7.0
       def primordial
         fetch('ancient.primordial')
       end
 
+      ##
+      # Produces a titan from ancient mythology.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Ancient.titan #=> "Atlas"
+      #
+      # @faker.version 1.7.0
       def titan
         fetch('ancient.titan')
       end
 
+      ##
+      # Produces a hero from ancient mythology.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Ancient.hero #=> "Achilles"
+      #
+      # @faker.version 1.7.0
       def hero
         fetch('ancient.hero')
       end