faker 2.7.0 → 2.8.1

data/lib/faker/default/bossa_nova.rb

@@ -3,10 +3,28 @@
 module Faker
   class BossaNova < Base
     class << self
+      ##
+      # Produces the name of a bossa nova artist.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::BossaNova.artist #=> "Tom Jobin"
+      #
+      # @faker.version 1.8.3
       def artist
         fetch('bossa_nova.artists')
       end
 
+      ##
+      # Produces a bossa nova song.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::BossaNova.song #=> "Chega de Saudade"
+      #
+      # @faker.version 1.8.3
       def song
         fetch('bossa_nova.songs')
       end

data/lib/faker/default/business.rb

@@ -7,14 +7,41 @@ module Faker
     flexible :business
 
     class << self
+      ##
+      # Produces a credit card number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Business.credit_card_number #=> "1228-1221-1221-1431"
+      #
+      # @faker.version 1.2.0
       def credit_card_number
         fetch('business.credit_card_numbers')
       end
 
+      ##
+      # Produces a credit card expiration date.
+      #
+      # @return [Date]
+      #
+      # @example
+      #   Faker::Business.credit_card_number #=> <Date: 2015-11-11 ((2457338j,0s,0n),+0s,2299161j)>
+      #
+      # @faker.version 1.2.0
       def credit_card_expiry_date
         ::Date.today + (365 * rand(1..4))
       end
 
+      ##
+      # Produces a type of credit card.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Business.credit_card_type #=> "visa"
+      #
+      # @faker.version 1.2.0
       def credit_card_type
         fetch('business.credit_card_types')
       end

data/lib/faker/default/chuck_norris.rb

@@ -5,7 +5,17 @@ module Faker
     flexible :chuck_norris
 
     class << self
-      # from: https://github.com/jenkinsci/chucknorris-plugin/blob/master/src/main/java/hudson/plugins/chucknorris/FactGenerator.java
+      # Produces a Chuck Norris Fact.
+      # Original list of facts:
+      # https://github.com/jenkinsci/chucknorris-plugin/blob/master/src/main/java/hudson/plugins/chucknorris/FactGenerator.java
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::ChuckNorris.fact
+      #     #=> "Chuck Norris can solve the Towers of Hanoi in one move."
+      #
+      # @faker.version 1.6.4
       def fact
         fetch('chuck_norris.fact')
       end

data/lib/faker/default/coffee.rb

@@ -5,24 +5,69 @@ module Faker
     flexible :coffee
 
     class << self
+      ##
+      # Produces a random blend name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Coffee.blend_name #=> "Major Java"
+      #
+      # @faker.version 1.9.0
       def blend_name
         parse('coffee.blend_name')
       end
 
+      ##
+      # Produces a random coffee origin place.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Coffee.origin #=> "Oaxaca, Mexico"
+      #
+      # @faker.version 1.9.0
       def origin
         country = fetch('coffee.country')
         region = fetch("coffee.regions.#{search_format(country)}")
         "#{region}, #{country}"
       end
 
+      ##
+      # Produces a random coffee variety.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Coffee.variety #=> "Red Bourbon"
+      #
+      # @faker.version 1.9.0
       def variety
         fetch('coffee.variety')
       end
 
+      ##
+      # Produces a string containing a random description of a coffee's taste.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Coffee.notes #=> "dull, tea-like, cantaloupe, soy sauce, marshmallow"
+      #
+      # @faker.version 1.9.0
       def notes
         parse('coffee.notes')
       end
 
+      ##
+      # Produces a random coffee taste intensity.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Coffee.intensifier #=> "mild"
+      #
+      # @faker.version 1.9.0
       def intensifier
         fetch('coffee.intensifier')
       end

data/lib/faker/default/coin.rb

@@ -3,10 +3,28 @@
 module Faker
   class Coin < Base
     class << self
+      ##
+      # Retrieves a random coin from any country.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Coin.name #=> "Brazilian Real"
+      #
+      # @faker.version 1.9.2
       def name
         fetch('currency.name')
       end
 
+      ##
+      # Retrieves a face to a flipped coin
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Coin.flip #=> "Heads"
+      #
+      # @faker.version 1.9.2
       def flip
         fetch('coin.flip')
       end

data/lib/faker/default/color.rb

@@ -3,27 +3,74 @@
 module Faker
   class Color < Base
     class << self
+      ##
+      # Produces a hex color code.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Color.hex_color #=> "#31a785"
+      #
+      # @faker.version 1.5.0
       def hex_color
         format('#%06x', (rand * 0xffffff))
       end
 
+      ##
+      # Produces the name of a color.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Color.color_name #=> "yellow"
+      #
+      # @faker.version 1.6.2
       def color_name
         fetch('color.name')
       end
 
+      # @private
       def single_rgb_color
         sample((0..255).to_a)
       end
 
+      ##
+      # Produces an array of integers representing an RGB color.
+      #
+      # @return [Array(Integer, Integer, Integer)]
+      #
+      # @example
+      #   Faker::Color.rgb_color #=> [54, 233, 67]
+      #
+      # @faker.version 1.5.0
       def rgb_color
         Array.new(3) { single_rgb_color }
       end
 
-      # returns [hue, saturation, lightness]
+      ##
+      # Produces an array of floats representing an HSL color.
+      # The array is in the form of `[hue, saturation, lightness]`.
+      #
+      # @return [Array(Float, Float, Float)]
+      #
+      # @example
+      #   Faker::Color.hsl_color #=> [69.87, 0.66, 0.3]
+      #
+      # @faker.version 1.5.0
       def hsl_color
         [sample((0..360).to_a), rand.round(2), rand.round(2)]
       end
 
+      ##
+      # Produces an array of floats representing an HSLA color.
+      # The array is in the form of `[hue, saturation, lightness, alpha]`.
+      #
+      # @return [Array(Float, Float, Float, Float)]
+      #
+      # @example
+      #   Faker::Color.hsla_color #=> [154.77, 0.36, 0.9, 0.2]
+      #
+      # @faker.version 1.5.0
       def hsla_color
         hsl_color << rand.round(1)
       end

data/lib/faker/default/crypto.rb

@@ -5,14 +5,41 @@ require 'digest'
 module Faker
   class Crypto < Base
     class << self
+      ##
+      # Produces an MD5 hash.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Crypto.md5 #=> "6b5ed240042e8a65c55ddb826c3408e6"
+      #
+      # @faker.version 1.6.4
       def md5
         Digest::MD5.hexdigest(Lorem.characters)
       end
 
+      ##
+      # Produces a SHA1 hash.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Crypto.sha1 #=> "4e99e31c51eef8b2d290e709f757f92e558a503f"
+      #
+      # @faker.version 1.6.4
       def sha1
         Digest::SHA1.hexdigest(Lorem.characters)
       end
 
+      ##
+      # Produces a SHA256 hash.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Crypto.sha256 #=> "51e4dbb424cd9db1ec5fb989514f2a35652ececef33f21c8dd1fd61bb8e3929d"
+      #
+      # @faker.version 1.6.4
       def sha256
         Digest::SHA256.hexdigest(Lorem.characters)
       end

data/lib/faker/default/currency.rb

@@ -3,14 +3,41 @@
 module Faker
   class Currency < Base
     class << self
+      ##
+      # Produces the name of a currency.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Currency.name #=> "Swedish Krona"
+      #
+      # @faker.version 1.9.0
       def name
         fetch('currency.name')
       end
 
+      ##
+      # Produces a currency code.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Currency.code #=> "USD"
+      #
+      # @faker.version 1.9.0
       def code
         fetch('currency.code')
       end
 
+      ##
+      # Produces a currency symbol.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Currency.symbol #=> "$"
+      #
+      # @faker.version 1.9.0
       def symbol
         fetch('currency.symbol')
       end

data/lib/faker/default/demographic.rb

@@ -3,26 +3,83 @@
 module Faker
   class Demographic < Base
     class << self
+      ##
+      # Produces the name of a race.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Demographic.race #=> "Native Hawaiian or Other Pacific Islander"
+      #
+      # @faker.version 1.7.3
       def race
         fetch('demographic.race')
       end
 
+      ##
+      # Produces a level of educational attainment.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Demographic.educational_attainment #=> "GED or alternative credential"
+      #
+      # @faker.version 1.7.3
       def educational_attainment
         fetch('demographic.educational_attainment')
       end
 
+      ##
+      # Produces a denonym.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Demographic.denonym #=> "Panamanian"
+      #
+      # @faker.version 1.7.3
       def demonym
         fetch('demographic.demonym')
       end
 
+      ##
+      # Produces a marital status.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Demographic.marital_status #=> "Widowed"
+      #
+      # @faker.version 1.7.3
       def marital_status
         fetch('demographic.marital_status')
       end
 
+      ##
+      # Produces a sex for demographic purposes.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Demographic.sex #=> "Female"
+      #
+      # @faker.version 1.7.3
       def sex
         fetch('demographic.sex')
       end
 
+      ##
+      # Produces a height as a string.
+      #
+      # @param unit [Symbol] either `:metric` or `imperial`.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Demographic.height #=> "1.61"
+      # @example
+      #   Faker::Demographic.height(unit: :imperial) #=> "6 ft, 2 in"
+      #
+      # @faker.version 1.7.3
       def height(legacy_unit = NOT_GIVEN, unit: :metric)
         warn_for_deprecated_arguments do |keywords|
           keywords << :unit if legacy_unit != NOT_GIVEN

data/lib/faker/default/educator.rb

@@ -5,30 +5,84 @@ module Faker
     flexible :educator
 
     class << self
+      ##
+      # Produces a university name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Educator.university #=> "Mallowtown Technical College"
+      #
+      # @faker.version 1.6.4
       def university
-        "#{parse('educator.name')} #{fetch('educator.tertiary.type')}"
+        parse('educator.university')
       end
 
+      ##
+      # Produces a university degree.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Educator.degree #=> "Associate Degree in Criminology"
+      #
+      # @faker.version 1.9.2
       def degree
-        "#{fetch('educator.tertiary.degree.type')} #{fetch('educator.tertiary.degree.subject')}"
+        parse('educator.degree')
       end
 
       alias course degree
 
+      ##
+      # Produces a university subject.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Educator.subject #=> "Criminology"
+      #
+      # @faker.version 1.9.2
       def subject
-        fetch('educator.tertiary.degree.subject')
+        fetch('educator.subject')
       end
 
+      ##
+      # Produces a course name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Educator.course_name #=> "Criminology 101"
+      #
+      # @faker.version 1.9.2
       def course_name
-        "#{fetch('educator.tertiary.degree.subject')} #{numerify(fetch('educator.tertiary.degree.course_number'))}"
+        numerify(parse('educator.course_name'))
       end
 
+      ##
+      # Produces a secondary school.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Educator.secondary_school #=> "Iceborough Secondary College"
+      #
+      # @faker.version 1.6.4
       def secondary_school
-        "#{parse('educator.name')} #{fetch('educator.secondary')}"
+        parse('educator.secondary_school')
       end
 
+      ##
+      # Produces a campus name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Educator.campus #=> "Vertapple Campus"
+      #
+      # @faker.version 1.6.4
       def campus
-        "#{parse('educator.name')} Campus"
+        parse('educator.campus')
       end
     end
   end