faker 2.11.0 → 2.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 27cbbd0c4b8240d56d669ed3edc77e0200a484b138415f17dcfb864977b162b6
-  data.tar.gz: 9abedbe42209cca1d53bc5b545716f4c14479c065d9b7d069844b1312648048a
+  metadata.gz: 2e07357f193be20c639621339c209b48ee1a99bb64528e2f3d2c4b61afed8b8b
+  data.tar.gz: 39d54382315e2fd6abe4b8275b5bee60c832ef2b045ae16bba46e82233ab7697
 SHA512:
-  metadata.gz: 4b29c27dddb232b1a27cf3829d724b14e45cf5628128b61be2566ff9ec235fc4d4a145f4e537c6fbfdd727b982f23325df4645d37d251cfb5cb59f7b7de73317
-  data.tar.gz: edea4ce978458ad1332d768d23cc988013b3b3e7c5e58d134da42a72c142ef7de77925efb4156fa7e1a32cd1e70820a654b038533abf72a048b419eb523396ea
+  metadata.gz: 16d0fdaf172d74ffa7c1cd1ae88e55801313f779e1d2be385941ec7dfa9b2922dacd104406eaa5f060545bbd3b33c840fa9f72f90637e3dc045d70706ab57a61
+  data.tar.gz: 5589900168ed8cb068fc6682751f1bc8edf6cbe6d8afc191aaf8668af05ee08edfeebb02e446748a18104623fe09f4205206dbc1b2600c732f3a7abc1d46d556

data/CHANGELOG.md

@@ -1,5 +1,94 @@
 # Change Log
 
+## [v2.12.0](https://github.com/faker-ruby/faker/tree/v2.12.0) (2020-05-31)
+
+This version:
+- adds several YARD docs
+- fixes some locale issues
+- fixes a few bugs in Faker generators
+- improves code quality
+- adds a few generators for Movies, Music and TV Shows
+- updates local dependencies
+
+## Bug/Fixes
+
+- [PR #2019](https://github.com/faker-ruby/faker/pull/2019) Update 'prepare' regexp to allow hyphen [@jbergenson](https://github.com/jbergenson)
+- [PR #2012](https://github.com/faker-ruby/faker/pull/2012) Add else condition to prevent false positive [@jbergenson](https://github.com/jbergenson)
+- [PR #1985](https://github.com/faker-ruby/faker/pull/1985) Fix an error for `Faker::Computer.os` [@koic](https://github.com/koic)
+- [PR #1971](https://github.com/faker-ruby/faker/pull/1971) Fixing the CI failure by fixing the infinite loop in Commerce [@amatsuda](https://github.com/amatsuda)
+
+## Chores
+
+- [PR #1988](https://github.com/faker-ruby/faker/pull/1988) Removing meaningless begin and end [@amatsuda](https://github.com/amatsuda)
+- [PR #1979](https://github.com/faker-ruby/faker/pull/1979) Reuse the `lvar` instead of calling `File.dirname(__FILE__)` again and again [@amatsuda](https://github.com/amatsuda)
+
+## Documentation
+
+- [PR #2022](https://github.com/faker-ruby/faker/pull/2022) Add YARD docs to `Faker::Invoice` [@danielTiringer](https://github.com/danielTiringer)
+- [PR #2021](https://github.com/faker-ruby/faker/pull/2021) Add YARD docs to `Faker::Hipster` [@danielTiringer](https://github.com/danielTiringer)
+- [PR #2020](https://github.com/faker-ruby/faker/pull/2020) Add YARD docs to `Faker::Measurement` [@danielTiringer](https://github.com/danielTiringer)
+- [PR #2017](https://github.com/faker-ruby/faker/pull/2017) Fix docs for `Faker::Games::Control.altered_world_event` [@Zeragamba](https://github.com/Zeragamba)
+- [PR #2016](https://github.com/faker-ruby/faker/pull/2016) Fix yard documentation issues [@danielTiringer](https://github.com/danielTiringer)
+- [PR #2015](https://github.com/faker-ruby/faker/pull/2015) Add YARD docs to `Faker::Quotes` [@danielTiringer](https://github.com/danielTiringer)
+- [PR #2011](https://github.com/faker-ruby/faker/pull/2011) Update `star_wars.yml` [@garrettmichaelgeorge](https://github.com/garrettmichaelgeorge)
+- [PR #2010](https://github.com/faker-ruby/faker/pull/2010) Add missing links in README.md [@Naokimi](https://github.com/Naokimi)
+- [PR #2009](https://github.com/faker-ruby/faker/pull/2009) Add YARD docs to `Faker::Placeholdit` [@danielTiringer](https://github.com/danielTiringer)
+- [PR #2008](https://github.com/faker-ruby/faker/pull/2008) Add YARD docs to `Faker::Verb` [@danielTiringer](https://github.com/danielTiringer)
+- [PR #2007](https://github.com/faker-ruby/faker/pull/2007) Add YARD docs to `Faker::Phone_Number` [@danielTiringer](https://github.com/danielTiringer)
+- [PR #2004](https://github.com/faker-ruby/faker/pull/2004) Add YARD docs to `Faker::String` [@danielTiringer](https://github.com/danielTiringer)
+- [PR #2001](https://github.com/faker-ruby/faker/pull/2001) Add YARD docs to `Faker::South_Africa` [@danielTiringer](https://github.com/danielTiringer)
+- [PR #2000](https://github.com/faker-ruby/faker/pull/2000) Add YARD docs to `Faker::JSON` [@danielTiringer](https://github.com/danielTiringer)
+- [PR #1999](https://github.com/faker-ruby/faker/pull/1999) Add YARD docs to `Faker::Types` [@danielTiringer](https://github.com/danielTiringer)
+- [PR #1998](https://github.com/faker-ruby/faker/pull/1998) Add YARD docs to `Faker::Finance` [@danielTiringer](https://github.com/danielTiringer)
+- [PR #1997](https://github.com/faker-ruby/faker/pull/1997) Add YARD docs to `Faker::Driving_Licence` [@danielTiringer](https://github.com/danielTiringer)
+- [PR #1996](https://github.com/faker-ruby/faker/pull/1996) Add YARD docs to `Crypto Coin` [@danielTiringer](https://github.com/danielTiringer)
+- [PR #1995](https://github.com/faker-ruby/faker/pull/1995) Add YARD docs to `Faker::Commerce` [@danielTiringer](https://github.com/danielTiringer)
+- [PR #1993](https://github.com/faker-ruby/faker/pull/1993) Add YARD docs to `Faker::Vehicle` [@danielTiringer](https://github.com/danielTiringer)
+- [PR #1990](https://github.com/faker-ruby/faker/pull/1990) Add YARD docs to `Faker::File` [@danielTiringer](https://github.com/danielTiringer)
+- [PR #1989](https://github.com/faker-ruby/faker/pull/1989) Add YARD docs to `Faker::Bank` [@danielTiringer](https://github.com/danielTiringer)
+- [PR #1984](https://github.com/faker-ruby/faker/pull/1984) Minor documentation fix for `Faker::University` [@Zeragamba](https://github.com/Zeragamba)
+- [PR #1983](https://github.com/faker-ruby/faker/pull/1983) Add YARD docs to `Faker::Twitter` [@danielTiringer](https://github.com/danielTiringer)
+- [PR #1982](https://github.com/faker-ruby/faker/pull/1982) Add YARD docs to `Faker::Cosmere` [@danielTiringer](https://github.com/danielTiringer)
+- [PR #1981](https://github.com/faker-ruby/faker/pull/1981) Add YARD docs to `Faker::Stripe` [@danielTiringer](https://github.com/danielTiringer)
+- [PR #1980](https://github.com/faker-ruby/faker/pull/1980) Add YARD docs to `Faker::Construction` [@danielTiringer](https://github.com/danielTiringer)
+- [PR #1976](https://github.com/faker-ruby/faker/pull/1976) Add YARD docs to `Faker::Name` [@danielTiringer](https://github.com/danielTiringer)
+- [PR #1975](https://github.com/faker-ruby/faker/pull/1975) Add YARD docs to `Faker::Compass` [@danielTiringer](https://github.com/danielTiringer)
+- [PR #1959](https://github.com/faker-ruby/faker/pull/1959) Add YARD docs to `Faker::University` [@danielTiringer](https://github.com/danielTiringer)
+- [PR #1956](https://github.com/faker-ruby/faker/pull/1956) Add YARD docs to `Faker::SlackEmoji` [@rutger-t](https://github.com/rutger-t)
+- [PR #1943](https://github.com/faker-ruby/faker/pull/1943) Update documentation for unique.exclude [@mtancoigne](https://github.com/mtancoigne)
+- [PR #1925](https://github.com/faker-ruby/faker/pull/1925) AdD `Faker::Game::WarhammerFantasy` [@sotek222](https://github.com/sotek222)
+
+## Feature Request
+
+- [PR #2025](https://github.com/faker-ruby/faker/pull/2025) Add `Faker::TvShows::Suits` [@ash-elangovan](https://github.com/ash-elangovan)
+- [PR #2024](https://github.com/faker-ruby/faker/pull/2024) Added Phish Albums and Musicians [@zfine416](https://github.com/zfine416)
+- [PR #2013](https://github.com/faker-ruby/faker/pull/2013) Add `Faker::Games::Control` [@Zeragamba](https://github.com/Zeragamba)
+- [PR #1994](https://github.com/faker-ruby/faker/pull/1994) Enable Ruby testing github workflow [@Zeragamba](https://github.com/Zeragamba)
+- [PR #1966](https://github.com/faker-ruby/faker/pull/1966) Add `Faker::Games:DnD` [@Naokimi](https://github.com/Naokimi)
+- [PR #1962](https://github.com/faker-ruby/faker/pull/1962) Adding Pearl Jam to the Music module [@briri](https://github.com/briri)
+- [PR #1960](https://github.com/faker-ruby/faker/pull/1960) Added `Faker::Blood` [@suraj32](https://github.com/suraj32)
+- [PR #1931](https://github.com/faker-ruby/faker/pull/1931) Add `Faker::Movies::Departed` Class [@jaebradley](https://github.com/jaebradley)
+- [PR #1696](https://github.com/faker-ruby/faker/pull/1696) Add Bibles class with King James subclass [@jbergenson](https://github.com/jbergenson)
+- [PR #1485](https://github.com/faker-ruby/faker/pull/1485) Plays and musicals [@armandofox](https://github.com/armandofox)
+
+## Update locales
+
+- [PR #2014](https://github.com/faker-ruby/faker/pull/2014) Make locale self-contained [@psibi](https://github.com/psibi)
+- [PR #1986](https://github.com/faker-ruby/faker/pull/1986) Added quotations to Shirahoshi [@iavivai](https://github.com/iavivai)
+- [PR #1973](https://github.com/faker-ruby/faker/pull/1973) Fix mis-quotations [@kayhide](https://github.com/kayhide)
+- [PR #1967](https://github.com/faker-ruby/faker/pull/1967) ko locale updates [@jae57](https://github.com/jae57)
+- [PR #1964](https://github.com/faker-ruby/faker/pull/1964) en-AU locale updates [@mattman](https://github.com/mattman)
+- [PR #1948](https://github.com/faker-ruby/faker/pull/1948) Add `Faker::Computer` [@cmcramer](https://github.com/cmcramer)
+
+## Update local dependencies
+
+- Update minitest requirement from = 5.14.0 to = 5.14.1 (#1987)
+- Update rubocop requirement from = 0.80.1 to = 0.81.0 (#1955)
+- Update pry requirement from = 0.13.0 to = 0.13.1 (#1963)
+- Update yard requirement from = 0.9.24 to = 0.9.25 (#1970)
+
+------------------------------------------------------------------------------
+
 ## [v2.11.0](https://github.com/faker-ruby/faker/tree/v2.11.0) (2020-03-24)
 
 ## Bug/Fixes

data/README.md

@@ -2,7 +2,7 @@
 ![logotype a happy-07](https://user-images.githubusercontent.com/36028424/40263395-4318481e-5b44-11e8-92e5-3dcc1ce169b3.png)
 
 # Faker
-[![Build Status](https://travis-ci.org/faker-ruby/faker.svg?branch=master)](https://travis-ci.org/faker-ruby/faker)
+[![Tests](https://github.com/faker-ruby/faker/workflows/Tests/badge.svg)](https://github.com/faker-ruby/faker/actions?query=workflow%3ATests)
 [![Gem Version](https://badge.fury.io/rb/faker.svg)](https://badge.fury.io/rb/faker)
 [![Inline docs](https://inch-ci.org/github/faker-ruby/faker.svg?branch=master)](https://inch-ci.org/github/faker-ruby/faker)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/ef54c7f9df86e965d64b/test_coverage)](https://codeclimate.com/github/stympy/faker/test_coverage)
@@ -95,7 +95,7 @@ manually set values).
 # Faker::<generator>.unique.exclude(method, arguments, list)
 
 # Add 'azerty' and 'wxcvbn' to the string generator with 6 char length
-Faker::Lorem.unique.exclude :string, [6], %w[azerty wxcvbn]
+Faker::Lorem.unique.exclude :string, [number: 6], %w[azerty wxcvbn]
 ```
 
 ### Deterministic Random
@@ -131,6 +131,7 @@ gem 'faker', :git => 'https://github.com/faker-ruby/faker.git', :branch => 'mast
   - [Faker::Avatar](doc/default/avatar.md)
   - [Faker::Bank](doc/default/bank.md)
   - [Faker::Beer](doc/default/beer.md)
+  - [Faker::Blood](doc/default/blood.md)
   - [Faker::Boolean](doc/default/boolean.md)
   - [Faker::BossaNova](doc/default/bossa_nova.md)
   - [Faker::Business](doc/default/business.md)
@@ -144,6 +145,7 @@ gem 'faker', :git => 'https://github.com/faker-ruby/faker.git', :branch => 'mast
   - [Faker::Commerce](doc/default/commerce.md)
   - [Faker::Company](doc/default/company.md)
   - [Faker::Compass](doc/default/compass.md)
+  - [Faker::Computer](doc/default/computer.md)
   - [Faker::Construction](doc/default/construction.md)
   - [Faker::Cosmere](doc/default/cosmere.md)
   - [Faker::Crypto](doc/default/crypto.md)
@@ -231,6 +233,7 @@ gem 'faker', :git => 'https://github.com/faker-ruby/faker.git', :branch => 'mast
 
 ### Games
   - [Faker::Game](doc/games/game.md)
+  - [Faker::Games::DnD](doc/games/dnd.md)
   - [Faker::Games::Dota](doc/games/dota.md)
   - [Faker::Games::ElderScrolls](doc/games/elder_scrolls.md)
   - [Faker::Games::Fallout](doc/games/fallout.md)
@@ -243,6 +246,7 @@ gem 'faker', :git => 'https://github.com/faker-ruby/faker.git', :branch => 'mast
   - [Faker::Games::Pokemon](doc/games/pokemon.md)
   - [Faker::Games::SonicTheHedgehog](doc/games/sonic_the_hedgehog.md)
   - [Faker::Games::SuperSmashBros](doc/games/super_smash_bros.md)
+  - [Faker::Games::WarhammerFantasy](doc/games/warhammer_fantasy.md)
   - [Faker::Games::Witcher](doc/games/witcher.md)
   - [Faker::Games::WorldOfWarcraft](doc/games/world_of_warcraft.md)
   - [Faker::Games::Zelda](doc/games/zelda.md)
@@ -255,6 +259,7 @@ gem 'faker', :git => 'https://github.com/faker-ruby/faker.git', :branch => 'mast
 ### Movies
   - [Faker::Movie](doc/movies/movie.md)
   - [Faker::Movies::BackToTheFuture](doc/movies/back_to_the_future.md)
+  - [Faker::Movies::Departed](doc/movies/departed.md)
   - [Faker::Movies::Ghostbusters](doc/movies/ghostbusters.md)
   - [Faker::Movies::HarryPotter](doc/movies/harry_potter.md)
   - [Faker::Movies::HitchhikersGuideToTheGalaxy](doc/movies/hitchhikers_guide_to_the_galaxy.md)
@@ -309,6 +314,7 @@ gem 'faker', :git => 'https://github.com/faker-ruby/faker.git', :branch => 'mast
   - [Faker::TvShows::StarTrek](doc/tv_shows/star_trek.md)
   - [Faker::TvShows::Stargate](doc/tv_shows/stargate.md)
   - [Faker::TvShows::StrangerThings](doc/tv_shows/stranger_things.md)
+  - [Faker::TvShows::Suits](doc/tv_shows/suits.md)
   - [Faker::TvShows::TheExpanse](doc/tv_shows/the_expanse.md)
   - [Faker::TvShows::TheFreshPrinceOfBelAir](doc/tv_shows/the_fresh_prince_of_bel_air.md)
   - [Faker::TvShows::TheITCrowd](doc/tv_shows/the_it_crowd.md)

data/lib/faker.rb

@@ -2,14 +2,11 @@
 
 mydir = __dir__
 
-begin
-  require 'psych'
-end
-
+require 'psych'
 require 'i18n'
 require 'set' # Fixes a bug in i18n 0.6.11
 
-Dir.glob(File.join(File.dirname(__FILE__), 'helpers', '*.rb')).sort.each { |file| require file }
+Dir.glob(File.join(mydir, 'helpers', '*.rb')).sort.each { |file| require file }
 
 I18n.load_path += Dir[File.join(mydir, 'locales', '**/*.yml')]
 I18n.reload! if I18n.backend.initialized?
@@ -132,7 +129,7 @@ module Faker
           # In either case the information will be retained for reconstruction of the string.
           text = prefix
 
-          # If the class has the method, call it, otherwise fetch the transation
+          # If the class has the method, call it, otherwise fetch the translation
           # (e.g., faker.phone_number.area_code)
           text += if cls.respond_to?(meth)
                     cls.send(meth)
@@ -225,8 +222,16 @@ module Faker
         @unique ||= UniqueGenerator.new(self, max_retries)
       end
 
-      def sample(list)
-        list.respond_to?(:sample) ? list.sample(random: Faker::Config.random) : list
+      def sample(list, num = nil)
+        if list.respond_to?(:sample)
+          if num
+            list.sample(num, random: Faker::Config.random)
+          else
+            list.sample(random: Faker::Config.random)
+          end
+        else
+          list
+        end
       end
 
       def shuffle(list)
@@ -307,4 +312,4 @@ module Faker
 end
 
 # require faker objects
-Dir.glob(File.join(File.dirname(__FILE__), 'faker', '/**/*.rb')).sort.each { |file| require file }
+Dir.glob(File.join(mydir, 'faker', '/**/*.rb')).sort.each { |file| require file }

data/lib/faker/default/address.rb

@@ -102,7 +102,7 @@ module Faker
       # @return [String]
       #
       # @example
-      # Faker::Address.mail_box #=> "PO Box 123"
+      #   Faker::Address.mail_box #=> "PO Box 123"
       #
       # @faker.version 2.9.1
       def mail_box

data/lib/faker/default/bank.rb

@@ -5,6 +5,17 @@ module Faker
     flexible :bank
 
     class << self
+      ##
+      # Produces a bank account number.
+      #
+      # @param digits [Integer] Number of digits that the generated account number should have.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Bank.account_number #=> 6738582379
+      #   Faker::Bank.account_number(digits: 13) #=> 673858237902
+      #
+      # @faker.version 1.9.1
       def account_number(legacy_digits = NOT_GIVEN, digits: 10)
         warn_for_deprecated_arguments do |keywords|
           keywords << :digits if legacy_digits != NOT_GIVEN
@@ -17,6 +28,17 @@ module Faker
         output[0...digits]
       end
 
+      ##
+      # Produces a bank iban number.
+      #
+      # @param country_code [String] Specifies what country prefix is used to generate the iban code.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Bank.iban #=> "GB76DZJM33188515981979"
+      #   Faker::Bank.iban(country_code: "be") #=> "BE6375388567752043"
+      #
+      # @faker.version 1.7.0
       def iban(legacy_country_code = NOT_GIVEN, country_code: 'GB')
         # Each country has its own format for bank accounts
         # Many of them use letters in certain parts of the account
@@ -38,22 +60,72 @@ module Faker
         country_code.upcase + iban_checksum(country_code, account) + account
       end
 
+      ##
+      # Produces a bank name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Bank.name #=> "ABN AMRO CORPORATE FINANCE LIMITED"
+      #
+      # @faker.version 1.7.0
       def name
         fetch('bank.name')
       end
 
+      ##
+      # Produces a routing number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Bank.routing_number #=> "729343831"
+      #
+      # @faker.version 1.9.1
       def routing_number
         valid_routing_number
       end
 
+      ##
+      # Produces a valid routing number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Bank.routing_number #=> "729343831"
+      #
+      # @faker.version 1.9.1
       def routing_number_with_format
         compile_fraction(valid_routing_number)
       end
 
+      ##
+      # Produces a swift / bic number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Bank.swift_bic #=> "AAFMGB21"
+      #
+      # @faker.version 1.7.0
       def swift_bic
         fetch('bank.swift_bic')
       end
 
+      ##
+      # Produces an Australian BSB (Bank-State-Branch) number
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Bank.bsb_number
+      #     #=> "036616"
+      #
+      # @faker.version next
+      def bsb_number
+        compile_bsb_number
+      end
+
       private
 
       def checksum(num_string)
@@ -72,6 +144,13 @@ module Faker
         routing_num
       end
 
+      def compile_bsb_number
+        digit_one_two = %w[01 03 06 08 11 12 73 76 78 30]
+        state = (2..7).to_a.map(&:to_s).sample
+        bsb_num = digit_one_two.sample + state + rand_numstring + rand_numstring + rand_numstring
+        bsb_num
+      end
+
       # Calculates the mandatory checksum in 3rd and 4th characters in IBAN format
       # source: https://en.wikipedia.org/wiki/International_Bank_Account_Number#Validating_the_IBAN
       def iban_checksum(country_code, account)

data/lib/faker/default/blood.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Faker
+  class Blood < Base
+    flexible :blood
+
+    class << self
+      ##
+      # Produces a random blood type.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Blood.type #=> "AB"
+      #
+      # @faker.version next
+      def type
+        fetch('blood.type')
+      end
+
+      ##
+      # Produces a random blood RH-Factor.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Blood.rh_factor #=> "-"
+      #
+      # @faker.version next
+      def rh_factor
+        fetch('blood.rh_factor')
+      end
+
+      ##
+      # Produces a random blood group name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Blood.group #=> "AB-"
+      #
+      # @faker.version next
+      def group
+        parse('blood.group')
+      end
+    end
+  end
+end

data/lib/faker/default/business.rb

@@ -26,7 +26,7 @@ module Faker
       # @return [Date]
       #
       # @example
-      #   Faker::Business.credit_card_number #=> <Date: 2015-11-11 ((2457338j,0s,0n),+0s,2299161j)>
+      #   Faker::Business.credit_card_expiry_date #=> <Date: 2015-11-11 ((2457338j,0s,0n),+0s,2299161j)>
       #
       # @faker.version 1.2.0
       def credit_card_expiry_date

data/lib/faker/default/commerce.rb

@@ -3,10 +3,30 @@
 module Faker
   class Commerce < Base
     class << self
+      ##
+      # Produces a random color.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Commerce.color #=> "lavender"
+      #
+      # @faker.version 1.2.0
       def color
         fetch('color.name')
       end
 
+      ##
+      # Produces a random promotion code.
+      #
+      # @param digits [Integer] Updates the number of numerical digits used to generate the promotion code.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Commerce.promotion_code #=> "AmazingDeal829102"
+      #   Faker::Commerce.promotion_code(digits: 2) #=> "AmazingPrice57"
+      #
+      # @faker.version 1.7.0
       def promotion_code(legacy_digits = NOT_GIVEN, digits: 6)
         warn_for_deprecated_arguments do |keywords|
           keywords << :digits if legacy_digits != NOT_GIVEN
@@ -19,6 +39,19 @@ module Faker
         ].join
       end
 
+      ##
+      # Produces a random department.
+      #
+      # @param max [Integer] Updates the maximum number of names used to generate the department name.
+      # @param fixed_amount [Boolean] Fixes the amount of departments to use instead of using a range.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Commerce.department #=> "Grocery, Health & Beauty"
+      #   Faker::Commerce.department(max: 5) #=> "Grocery, Books, Health & Beauty"
+      #   Faker::Commerce.department(max: 2, fixed_amount: true) #=> "Books & Tools"
+      #
+      # @faker.version 1.2.0
       def department(legacy_max = NOT_GIVEN, legacy_fixed_amount = NOT_GIVEN, max: 3, fixed_amount: false)
         warn_for_deprecated_arguments do |keywords|
           keywords << :max if legacy_max != NOT_GIVEN
@@ -30,19 +63,55 @@ module Faker
 
         categories = categories(num)
 
-        return merge_categories(categories) if num > 1
-
-        categories[0]
+        if categories.is_a?(Array)
+          if categories.length > 1
+            merge_categories(categories)
+          else
+            categories[0]
+          end
+        else
+          categories
+        end
       end
 
+      ##
+      # Produces a random product name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Commerce.product_name #=> "Practical Granite Shirt"
+      #
+      # @faker.version 1.2.0
       def product_name
         "#{fetch('commerce.product_name.adjective')} #{fetch('commerce.product_name.material')} #{fetch('commerce.product_name.product')}"
       end
 
+      ##
+      # Produces a random material.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Commerce.material #=> "Plastic"
+      #
+      # @faker.version 1.5.0
       def material
         fetch('commerce.product_name.material')
       end
 
+      ##
+      # Produces a random product price.
+      #
+      # @param range [Range] A range to generate the random number within.
+      # @param as_string [Boolean] Changes the return value to [String].
+      # @return [Float]
+      #
+      # @example
+      #   Faker::Commerce.price #=> 44.6
+      #   Faker::Commerce.price(range: 0..10.0, as_string: true) #=> "2.18"
+      #
+      # @faker.version 1.2.0
       def price(legacy_range = NOT_GIVEN, legacy_as_string = NOT_GIVEN, range: 0..100.0, as_string: false)
         warn_for_deprecated_arguments do |keywords|
           keywords << :range if legacy_range != NOT_GIVEN
@@ -60,13 +129,7 @@ module Faker
       private
 
       def categories(num)
-        categories = []
-        while categories.length < num
-          category = fetch('commerce.department')
-          categories << category unless categories.include?(category)
-        end
-
-        categories
+        sample(fetch_all('commerce.department'), num)
       end
 
       def merge_categories(categories)