faker 2.4.0 → 2.5.0

data/lib/faker/default/restaurant.rb

@@ -4,8 +4,60 @@ module Faker
   class Restaurant < Base
     flexible :restaurant
 
-    def self.name
-      bothify(parse('restaurant.name'))
+    class << self
+      ##
+      # Produces the name of a restaurant.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Restaurant.name #=> "Curry King"
+      #
+      # @faker.version 1.9.2
+      def name
+        bothify(parse('restaurant.name'))
+      end
+
+      ##
+      # Produces a type of restaurant.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Restaurant.type #=> "Comfort Food"
+      #
+      # @faker.version 1.9.2
+      def type
+        fetch('restaurant.type')
+      end
+
+      ##
+      # Produces a description of a restaurant.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Restaurant.description
+      #     #=> "We are committed to using the finest ingredients in our recipes. No food leaves our kitchen that we ourselves would not eat."
+      #
+      # @faker.version 1.9.2
+      def description
+        fetch('restaurant.description')
+      end
+
+      ##
+      # Produces a review for a restaurant.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Restaurant.review
+      #     #=> "Brand new. Great design. Odd to hear pop music in a Mexican establishment. Music is a bit loud. It should be background."
+      #
+      # @faker.version 1.9.2
+      def review
+        fetch('restaurant.review')
+      end
     end
   end
 end

data/lib/faker/default/time.rb

@@ -14,8 +14,31 @@ module Faker
 
     class << self
       # rubocop:disable Metrics/ParameterLists
+      # rubocop:disable Style/AsciiComments
+
+      ##
+      # Produce a random time between two times.
+      #
+      # @param from [Time, Date, DateTime] The start of the usable time range.
+      # @param to [Time, Date, DateTime] The end of the usable time range.
+      # @param format [Symbol] The name of a DateTime format to use.
+      # @return [Time]
+      #
+      # @example
+      #   # Random Stringified time between two times, formatted to the specified I18n format
+      #   # (Examples are from a Rails console with rails-i18n 5.1.1 defaults loaded)
+      #   I18n.locale = 'en-US'
+      #   Faker::Time.between(from: DateTime.now - 1, to: DateTime.now, format: :default) #=> "Tue, 16 Oct 2018 10:48:27 AM -05:00"
+      #   Faker::Time.between(from: DateTime.now - 1, to: DateTime.now, format: :short) #=> "15 Oct 10:48 AM"
+      #   Faker::Time.between(from: DateTime.now - 1, to: DateTime.now, format: :long) #=> "October 15, 2018 10:48 AM"
+      #
+      #   I18n.locale = 'ja'
+      #   Faker::Time.between(from: DateTime.now - 1, to: DateTime.now, format: :default) #=> "2018/10/15 10:48:27"
+      #   Faker::Time.between(from: DateTime.now - 1, to: DateTime.now, format: :short) #=> "18/10/15 10:48"
+      #   Faker::Time.between(from: DateTime.now - 1, to: DateTime.now, format: :long) #=> "2018年10月16日(火) 10時48分27秒 -0500"
+      #
+      # @faker.version 1.5.0
       def between(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, legacy_format = NOT_GIVEN, from:, to:, format: nil)
-        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :from if legacy_from != NOT_GIVEN
           keywords << :to if legacy_to != NOT_GIVEN
@@ -28,10 +51,37 @@ module Faker
         time = Faker::Base.rand_in_range(from, to)
         time_with_format(time, format)
       end
-
-      # rubocop:disable Metrics/ParameterLists
+      # rubocop:enable Style/AsciiComments
+
+      ##
+      # Produce a random time between two dates.
+      #
+      # @param from [Date] The start of the usable time range.
+      # @param to [Date] The end of the usable time range.
+      # @param period [Symbol] The time of day, if any. See {TIME_RANGES}.
+      # @param format [Symbol] The name of a DateTime format to use.
+      # @return [Time]
+      #
+      # @example
+      #   Faker::Time.between_dates(from: Date.today - 1, to: Date.today, period: :all)
+      #     #=> "2014-09-19 07:03:30 -0700"
+      #   Faker::Time.between_dates(from: Date.today - 1, to: Date.today, period: :day)
+      #     #=> "2014-09-18 16:28:13 -0700"
+      #   Faker::Time.between_dates(from: Date.today - 1, to: Date.today, period: :night)
+      #     #=> "2014-09-20 19:39:38 -0700"
+      #   Faker::Time.between_dates(from: Date.today - 1, to: Date.today, period: :morning)
+      #     #=> "2014-09-19 08:07:52 -0700"
+      #   Faker::Time.between_dates(from: Date.today - 1, to: Date.today, period: :afternoon)
+      #     #=> "2014-09-18 12:10:34 -0700"
+      #   Faker::Time.between_dates(from: Date.today - 1, to: Date.today, period: :evening)
+      #     #=> "2014-09-19 20:21:03 -0700"
+      #   Faker::Time.between_dates(from: Date.today - 1, to: Date.today, period: :midnight)
+      #     #=> "2014-09-20 00:40:14 -0700"
+      #   Faker::Time.between_dates(from: Date.today - 5, to: Date.today + 5, period: :afternoon, format: :default)
+      #     #=> "Fri, 19 Oct 2018 15:17:46 -0500"
+      #
+      # @faker.version 1.0.0
       def between_dates(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, legacy_period = NOT_GIVEN, legacy_format = NOT_GIVEN, from:, to:, period: :all, format: nil)
-        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :from if legacy_from != NOT_GIVEN
           keywords << :to if legacy_to != NOT_GIVEN
@@ -44,9 +94,22 @@ module Faker
         time_with_format(time, format)
       end
 
-      # rubocop:disable Metrics/ParameterLists
+      ##
+      # Produce a random time in the future (up to N days).
+      #
+      # @param days [Integer] The maximum number of days to go into the future.
+      # @param period [Symbol] The time of day, if any. See {TIME_RANGES}.
+      # @param format [Symbol] The name of a DateTime format to use.
+      # @return [Time]
+      #
+      # @example
+      #   Faker::Time.forward(days: 23, period: :morning)
+      #     # => "2014-09-26 06:54:47 -0700"
+      #   Faker::Time.forward(days: 5,  period: :evening, format: :long)
+      #     #=> "October 21, 2018 20:47"
+      #
+      # @faker.version 1.5.0
       def forward(legacy_days = NOT_GIVEN, legacy_period = NOT_GIVEN, legacy_format = NOT_GIVEN, days: 365, period: :all, format: nil)
-        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :days if legacy_days != NOT_GIVEN
           keywords << :period if legacy_period != NOT_GIVEN
@@ -56,9 +119,22 @@ module Faker
         time_with_format(date_with_random_time(Faker::Date.forward(days: days), period), format)
       end
 
-      # rubocop:disable Metrics/ParameterLists
+      ##
+      # Produce a random time in the past (up to N days).
+      #
+      # @param days [Integer] The maximum number of days to go into the past.
+      # @param period [Symbol] The time of day, if any. See {TIME_RANGES}.
+      # @param format [Symbol] The name of a DateTime format to use.
+      # @return [Time]
+      #
+      # @example
+      #   Faker::Time.backward(days: 14, period: :evening)
+      #     #=> "2014-09-17 19:56:33 -0700"
+      #   Faker::Time.backward(days: 5, period: :morning, format: :short)
+      #     #=> "14 Oct 07:44"
+      #
+      # @faker.version 1.5.0
       def backward(legacy_days = NOT_GIVEN, legacy_period = NOT_GIVEN, legacy_format = NOT_GIVEN, days: 365, period: :all, format: nil)
-        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :days if legacy_days != NOT_GIVEN
           keywords << :period if legacy_period != NOT_GIVEN
@@ -67,6 +143,7 @@ module Faker
 
         time_with_format(date_with_random_time(Faker::Date.backward(days: days), period), format)
       end
+      # rubocop:enable Metrics/ParameterLists
 
       private
 

data/lib/faker/games/zelda.rb

@@ -3,7 +3,7 @@
 module Faker
   class Games
     class Zelda < Base
-      flexible :space
+      flexible :zelda
       class << self
         ##
         # Produces the name of a Legend of Zelda game.

data/lib/faker/japanese_media/one_piece.rb

@@ -4,26 +4,80 @@ module Faker
   class JapaneseMedia
     class OnePiece < Base
       class << self
+        ##
+        # Produces a character from One Piece.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::JapaneseMedia::OnePiece.character #=> "Monkey D. Luffy"
+        #
+        # @faker.version 1.8.5
         def character
           fetch('one_piece.characters')
         end
 
+        ##
+        # Produces a sea from One Piece.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::JapaneseMedia::OnePiece.sea #=> "East Blue"
+        #
+        # @faker.version 1.8.5
         def sea
           fetch('one_piece.seas')
         end
 
+        ##
+        # Produces an island from One Piece.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::JapaneseMedia::OnePiece.island #=> "Laftel"
+        #
+        # @faker.version 1.8.5
         def island
           fetch('one_piece.islands')
         end
 
+        ##
+        # Produces a location from One Piece.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::JapaneseMedia::OnePiece.location #=> "Foosha Village"
+        #
+        # @faker.version 1.8.5
         def location
           fetch('one_piece.locations')
         end
 
+        ##
+        # Produces a quote from One Piece.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::JapaneseMedia::OnePiece.quote #=> "ONE PIECE IS REAL!"
+        #
+        # @faker.version 1.8.5
         def quote
           fetch('one_piece.quotes')
         end
 
+        ##
+        # Produces an akuma no mi from One Piece.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::JapaneseMedia::OnePiece.akuma_no_mi #=> "Gomu Gomu no Mi"
+        #
+        # @faker.version 1.8.5
         def akuma_no_mi
           fetch('one_piece.akumas_no_mi')
         end

data/lib/faker/movies/back_to_the_future.rb

@@ -4,14 +4,42 @@ module Faker
   class Movies
     class BackToTheFuture < Base
       class << self
+        ##
+        # Produces a character from Back to the Future.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Movies::BackToTheFuture.character #=> "Marty McFly"
+        #
+        # @faker.version 1.8.5
         def character
           fetch('back_to_the_future.characters')
         end
 
+        ##
+        # Produces a date from Back to the Future.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Movies::BackToTheFuture.date #=> "November 5, 1955"
+        #
+        # @faker.version 1.8.5
         def date
           fetch('back_to_the_future.dates')
         end
 
+        ##
+        # Produces a quote from Back to the Future.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Movies::BackToTheFuture.quote
+        #     #=> "Roads? Where we're going, we don't need roads."
+        #
+        # @faker.version 1.8.5
         def quote
           fetch('back_to_the_future.quotes')
         end

data/lib/faker/movies/ghostbusters.rb

@@ -4,14 +4,42 @@ module Faker
   class Movies
     class Ghostbusters < Base
       class << self
+        ##
+        # Produces an actor from Ghostbusters.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Movies::Ghostbusters.actor #=> "Bill Murray"
+        #
+        # @faker.version 1.9.2
         def actor
           fetch('ghostbusters.actors')
         end
 
+        ##
+        # Produces a character from Ghostbusters.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Movies::Ghostbusters.character #=> "Dr. Egon Spengler"
+        #
+        # @faker.version 1.9.2
         def character
           fetch('ghostbusters.characters')
         end
 
+        ##
+        # Produces a quote from Ghostbusters.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Movies::Ghostbusters.quote
+        #     #=> "I tried to think of the most harmless thing. Something I loved from my childhood. Something that could never ever possibly destroy us. Mr. Stay Puft!"
+        #
+        # @faker.version 1.9.2
         def quote
           fetch('ghostbusters.quotes')
         end

data/lib/faker/movies/harry_potter.rb

@@ -4,26 +4,80 @@ module Faker
   class Movies
     class HarryPotter < Base
       class << self
+        ##
+        # Produces a character from Harry Potter.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Movies::HarryPotter.character #=> "Harry Potter"
+        #
+        # @faker.version 1.7.3
         def character
           fetch('harry_potter.characters')
         end
 
+        ##
+        # Produces a location from Harry Potter.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Movies::HarryPotter.location #=> "Hogwarts"
+        #
+        # @faker.version 1.7.3
         def location
           fetch('harry_potter.locations')
         end
 
+        ##
+        # Produces a quote from Harry Potter.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Movies::HarryPotter.quote #=> "I solemnly swear that I am up to good."
+        #
+        # @faker.version 1.7.3
         def quote
           fetch('harry_potter.quotes')
         end
 
+        ##
+        # Produces a book from Harry Potter.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Movies::HarryPotter.book #=> "Harry Potter and the Chamber of Secrets"
+        #
+        # @faker.version 1.7.3
         def book
           fetch('harry_potter.books')
         end
 
+        ##
+        # Produces a house from Harry Potter.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Movies::HarryPotter.house #=> "Gryffindor"
+        #
+        # @faker.version 1.7.3
         def house
           fetch('harry_potter.houses')
         end
 
+        ##
+        # Produces a spell from Harry Potter.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Movies::HarryPotter.spell #=> "Reparo"
+        #
+        # @faker.version 1.7.3
         def spell
           fetch('harry_potter.spells')
         end