faker 2.2.2 → 2.3.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/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,18 +3,63 @@
 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
 
+      ##
+      # 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
       # rubocop:disable Metrics/ParameterLists
       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

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,8 +3,39 @@
 module Faker
   class Avatar < Base
     class << self
+      # @private
       SUPPORTED_FORMATS = %w[png jpg bmp].freeze
 
+      ##
+      # 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
       # rubocop:disable Metrics/ParameterLists
       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

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

@@ -3,10 +3,28 @@
 module Faker
   class Gender < Base
     class << self
+      ##
+      # Produces the name of a gender identity.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Gender.type #=> "Non-binary"
+      #
+      # @faker.version 1.9.0
       def type
         fetch('gender.types')
       end
 
+      ##
+      # Produces either 'Male' or 'Female'.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Gender.binary_type #=> "Female"
+      #
+      # @faker.version 1.9.0
       def binary_type
         fetch('gender.binary_types')
       end

data/lib/faker/default/hacker.rb

@@ -1,35 +1,93 @@
 # frozen_string_literal: true
 
-# Port of http://shinytoylabs.com/jargon/
 module Faker
+  # Port of http://shinytoylabs.com/jargon/
+  # Are you having trouble writing tech-savvy dialogue for your latest screenplay?
+  # Worry not! Hollywood-grade technical talk is ready to fill out any form where you need to look smart.
   class Hacker < Base
     flexible :hacker
 
     class << self
+      ##
+      # Produces something smart.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Hacker.say_something_smart
+      #     #=> "Try to compress the SQL interface, maybe it will program the back-end hard drive!"
+      #
+      # @faker.version 1.4.0
       def say_something_smart
         sample(phrases)
       end
 
+      ##
+      # Short technical abbreviations.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Hacker.abbreviation #=> "RAM"
+      #
+      # @faker.version 1.4.0
       def abbreviation
         fetch('hacker.abbreviation')
       end
 
+      ##
+      # Hacker-centric adjectives.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Hacker.adjective #=> "open-source"
+      #
+      # @faker.version 1.4.0
       def adjective
         fetch('hacker.adjective')
       end
 
+      ##
+      # Only the best hacker-related nouns.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Hacker.noun #=> "bandwidth"
+      #
+      # @faker.version 1.4.0
       def noun
         fetch('hacker.noun')
       end
 
+      ##
+      # Actions that hackers take.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Hacker.verb #=> "bypass"
+      #
+      # @faker.version 1.4.0
       def verb
         fetch('hacker.verb')
       end
 
+      ##
+      # Produces a verb that ends with '-ing'.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Hacker.ingverb #=> "synthesizing"
+      #
+      # @faker.version 1.4.0
       def ingverb
         fetch('hacker.ingverb')
       end
 
+      # @private
       def phrases
         ["If we #{verb} the #{noun}, we can get to the #{abbreviation} #{noun} through the #{adjective} #{abbreviation} #{noun}!",
          "We need to #{verb} the #{adjective} #{abbreviation} #{noun}!",