Prepare Faker::Time.between deprecation (faker-ruby#1287)

* Prepare Faker::Time.between deprecation [1282](faker-ruby#1282)

* Prepare Faker::Time.between deprecation (documentation)

* Prepare Faker::Time.between deprecation (documentation)

CHANGELOG.md

@@ -123,6 +123,8 @@
 ### Deprecation
 - [PR #1264](https://github.com/stympy/faker/pull/1264) Prepare Faker::Name.job_titles and Faker::Name.title for deprecation
   - Removing these methods as they are available in `Faker::Job`
+- [PR #1287](https://github.com/stympy/faker/pull/1287) Prepare Faker::Time.between for deprecation
+  - This method will only return Time Objects. For DateTime Objects there will be a new class Faker::DateTime
 
 ## [v1.8.7](https://github.com/stympy/faker/tree/v1.8.7) (2017-12-22)
 [Full Changelog](https://github.com/stympy/faker/compare/v1.8.6...v1.8.7)

doc/time.md

@@ -21,4 +21,13 @@ Faker::Time.forward(23, :morning) # => "2014-09-26 06:54:47 -0700"
 
 # Random time in the past (up to maximum of N days)
 Faker::Time.backward(14, :evening) #=> "2014-09-17 19:56:33 -0700"
+
+# Option by default is :all, and it will return a DateTime object
+# If you want to get a Time object between 2 times you have to specify the option :between
+# Random time in the las 3 hours
+Faker::Time.between(3.hours.ago, Time.now, :between) #=> "Wed, 20 Jun 2018 10:30:02 UTC +00:00"
 ```
+
+### NOTE
+
+* Faker.Time.between will be deprecated. After deprecation it will only return Time objects. For DateTime objects there wil be a new class Faker::DateTime

lib/faker/time.rb

@@ -11,6 +11,8 @@ class Time < Faker::Date
     }.freeze
 
     class << self
+      extend Gem::Deprecate
+
       def between(from, to, period = :all, format = nil)
         time = period == :between ? rand(from..to) : date_with_random_time(super(from, to), period)
         time_with_format(time, format)
@@ -46,6 +48,8 @@ def minutes
       def seconds
         sample((0..59).to_a)
       end
+
+      deprecate :between, 'Faker::Time.between', 2018, 9
     end
   end
 end