faker 2.2.2 → 2.7.0

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/alphanumeric.rb

@@ -2,9 +2,23 @@
 
 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)
         warn_for_deprecated_arguments do |keywords|
           keywords << :number if legacy_number != NOT_GIVEN
@@ -18,15 +32,18 @@ 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)

data/lib/faker/default/app.rb

@@ -3,19 +3,65 @@
 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
         warn_for_deprecated_arguments do |keywords|

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

data/lib/faker/default/avatar.rb

@@ -3,9 +3,41 @@
 module Faker
   class Avatar < Base
     class << self
+      # @private
       SUPPORTED_FORMATS = %w[png jpg bmp].freeze
 
       # rubocop:disable Metrics/ParameterLists
+
+      ##
+      # Produces a URL for an avatar from robohash.org
+      #
+      # @param slug [String, nil]
+      # @param size [String] image size in pixels, in the format of 'AxB'
+      # @param format [String] The image file format
+      # @param set [String] The avatar set to use
+      # @param bgset [String, nil] The background set to use
+      # @return [String] A robohash.org URL
+      #
+      # @example
+      #   Faker::Avatar.image
+      #     #=> "https://robohash.org/sitsequiquia.png?size=300x300&set=set1"
+      # @example
+      #   Faker::Avatar.image(slug: "my-own-slug")
+      #     #=> "https://robohash.org/my-own-slug.png?size=300x300&set=set1"
+      # @example
+      #   Faker::Avatar.image(slug: "my-own-slug", size: "50x50")
+      #     #=> "https://robohash.org/my-own-slug.png?size=50x50&set=set1"
+      # @example
+      #   Faker::Avatar.image(slug: "my-own-slug", size: "50x50", format: "jpg")
+      #     #=> "https://robohash.org/my-own-slug.jpg?size=50x50&set=set1"
+      # @example
+      #   Faker::Avatar.image(slug: "my-own-slug", size: "50x50", format: "bmp")
+      #     #=> "https://robohash.org/my-own-slug.bmp?size=50x50&set=set1"
+      # @example
+      #   Faker::Avatar.image(slug: "my-own-slug", size: "50x50", format: "bmp", set: "set1", bgset: "bg1")
+      #     #=> "https://robohash.org/my-own-slug.bmp?size=50x50&set=set1&bgset=bg1"
+      #
+      # @faker.version 1.4.3
       def image(legacy_slug = NOT_GIVEN, legacy_size = NOT_GIVEN, legacy_format = NOT_GIVEN, legacy_set = NOT_GIVEN, legacy_bgset = NOT_GIVEN, slug: nil, size: '300x300', format: 'png', set: 'set1', bgset: nil)
         # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|

data/lib/faker/default/boolean.rb

@@ -3,11 +3,22 @@
 module Faker
   class Boolean < Base
     class << self
+      ##
+      # Produces a boolean
+      #
+      # @param true_ratio [Float] The likelihood (as a float, out of 1.0) for the method to return `true`.
+      # @return [Boolean]
+      #
+      # @example
+      #   Faker::Boolean.boolean #=> true
+      # @example
+      #   Faker::Boolean.boolean(true_ratio: 0.2) #=> false
+      #
+      # @faker.version 1.6.2
       def boolean(legacy_true_ratio = NOT_GIVEN, true_ratio: 0.5)
         warn_for_deprecated_arguments do |keywords|
           keywords << :true_ratio if legacy_true_ratio != NOT_GIVEN
         end
-
         (rand < true_ratio)
       end
     end

data/lib/faker/default/chuck_norris.rb

@@ -2,7 +2,7 @@
 
 module Faker
   class ChuckNorris < Base
-    flexible :name
+    flexible :chuck_norris
 
     class << self
       # from: https://github.com/jenkinsci/chucknorris-plugin/blob/master/src/main/java/hudson/plugins/chucknorris/FactGenerator.java

data/lib/faker/default/date.rb

@@ -3,6 +3,18 @@
 module Faker
   class Date < Base
     class << self
+      ##
+      # Produce a random date between two dates.
+      #
+      # @param from [Date] The start of the usable date range.
+      # @param to [Date] The end of the usable date range.
+      # @return [Date]
+      #
+      # @example
+      #   Faker::Date.between(from: 2.days.ago, to: Date.today)
+      #     #=> #<Date: 2014-09-24>
+      #
+      # @faker.version 1.0.0
       def between(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from:, to:)
         warn_for_deprecated_arguments do |keywords|
           keywords << :from if legacy_from != NOT_GIVEN
@@ -16,8 +28,21 @@ module Faker
       end
 
       # rubocop:disable Metrics/ParameterLists
+
+      ##
+      # Produce a random date between two dates.
+      #
+      # @param from [Date] The start of the usable date range.
+      # @param to [Date] The end of the usable date range.
+      # @param excepted [Date] A date to exclude.
+      # @return [Date]
+      #
+      # @example
+      #   Faker::Date.between_except(from: 1.year.ago, to: 1.year.from_now, excepted: Date.today)
+      #     #=> #<Date: 2014-10-03>
+      #
+      # @faker.version 1.6.2
       def between_except(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, legacy_excepted = NOT_GIVEN, from:, to:, excepted:)
-        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :from if legacy_from != NOT_GIVEN
         end
@@ -37,7 +62,18 @@ module Faker
           break date.to_date if date != excepted
         end
       end
-
+      # rubocop:enable Metrics/ParameterLists
+
+      ##
+      # Produce a random date in the future (up to N days).
+      #
+      # @param days [Integer] The maximum number of days to go into the future.
+      # @return [Date]
+      #
+      # @example
+      #   Faker::Date.forward(days: 23) #=> #<Date: 2014-10-03>
+      #
+      # @faker.version 1.0.0
       def forward(legacy_days = NOT_GIVEN, days: 365)
         warn_for_deprecated_arguments do |keywords|
           keywords << :days if legacy_days != NOT_GIVEN
@@ -49,6 +85,16 @@ module Faker
         between(from: from, to: to).to_date
       end
 
+      ##
+      # Produce a random date in the past (up to N days).
+      #
+      # @param days [Integer] The maximum number of days to go into the past.
+      # @return [Date]
+      #
+      # @example
+      #   Faker::Date.backward(days: 14) #=> #<Date: 2019-09-12>
+      #
+      # @faker.version 1.0.0
       def backward(legacy_days = NOT_GIVEN, days: 365)
         warn_for_deprecated_arguments do |keywords|
           keywords << :days if legacy_days != NOT_GIVEN
@@ -60,6 +106,17 @@ module Faker
         between(from: from, to: to).to_date
       end
 
+      ##
+      # Produce a random date in the past (up to N days).
+      #
+      # @param min_age [Integer] The minimum age that the birthday would imply.
+      # @param max_age [Integer] The maximum age that the birthday would imply.
+      # @return [Date]
+      #
+      # @example
+      #   Faker::Date.birthday(min_age: 18, max_age: 65) #=> #<Date: 1986-03-28>
+      #
+      # @faker.version 1.4.3
       def birthday(legacy_min_age = NOT_GIVEN, legacy_max_age = NOT_GIVEN, min_age: 18, max_age: 65)
         warn_for_deprecated_arguments do |keywords|
           keywords << :min_age if legacy_min_age != NOT_GIVEN
@@ -76,6 +133,30 @@ module Faker
         between(from: from, to: to).to_date
       end
 
+      ##
+      # Produces a date in the year and/or month specified.
+      #
+      # @param month [Integer] represents the month of the date
+      # @param year [Integer] represents the year of the date
+      # @return [Date]
+      #
+      # @example
+      #   Faker::Date.in_date_period #=> #<Date: 2019-09-01>
+      #
+      # @example
+      #   Faker::Date.in_date_period(year: 2018, month: 2) #=> #<Date: 2018-02-26>
+      #
+      # @example
+      #   Faker::Date.in_date_period(month: 2) #=> #<Date: 2019-02-26>
+      #
+      # @faker.version next
+      def in_date_period(month: nil, year: ::Date.today.year)
+        from = ::Date.new(year, month || 1, 1)
+        to = ::Date.new(year, month || 12, ::Date.civil(year, month || 12, -1).day)
+
+        between(from: from, to: to).to_date
+      end
+
       private
 
       def birthday_date(date, age)