Update some YARD docs to resolve feedback.

Fix some phrasing, add missing version tags, fix a Rubocop warning by
disabling the cop, and clarify the possible values for period in
Faker::Time.

lib/faker/default/date.rb

@@ -13,6 +13,8 @@ class << self
       # @example
       #   Faker::Date.between(from: 2.days.ago, to: Date.today)
       #     #=> "Wed, 24 Sep 2014"
+      #
+      # @faker.version 1.0.0
       def between(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from:, to:)
         warn_for_deprecated_arguments do |keywords|
           keywords << :from if legacy_from != NOT_GIVEN
@@ -32,7 +34,7 @@ def between(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from:, to:)
       #
       # @param from [Date] The start of the usable date range.
       # @param to [Date] The end of the usable date range.
-      # @param excepted [Date] A date not to exclude.
+      # @param excepted [Date] A date to exclude.
       # @return [Date]
       #
       # @example
@@ -70,6 +72,8 @@ def between_except(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, legacy_except
       #
       # @example
       #   Faker::Date.forward(days: 23) # => "Fri, 03 Oct 2014"
+      #
+      # @faker.version 1.0.0
       def forward(legacy_days = NOT_GIVEN, days: 365)
         warn_for_deprecated_arguments do |keywords|
           keywords << :days if legacy_days != NOT_GIVEN
@@ -89,6 +93,8 @@ def forward(legacy_days = NOT_GIVEN, days: 365)
       #
       # @example
       #   Faker::Date.backward(days: 14) #=> "Fri, 19 Sep 2014"
+      #
+      # @faker.version 1.0.0
       def backward(legacy_days = NOT_GIVEN, days: 365)
         warn_for_deprecated_arguments do |keywords|
           keywords << :days if legacy_days != NOT_GIVEN

lib/faker/default/number.rb

@@ -11,6 +11,8 @@ class << self
       #
       # @example
       #   Faker::Number.number(digits: 10) #=> 1968353479
+      #
+      # @faker.version 1.0.0
       def number(legacy_digits = NOT_GIVEN, digits: 10)
         warn_for_deprecated_arguments do |keywords|
           keywords << :digits if legacy_digits != NOT_GIVEN
@@ -31,6 +33,8 @@ def number(legacy_digits = NOT_GIVEN, digits: 10)
       #
       # @example
       #   Faker::Number.leading_zero_number(digits: 10) #=> "0669336915"
+      #
+      # @faker.version 1.0.0
       def leading_zero_number(legacy_digits = NOT_GIVEN, digits: 10)
         warn_for_deprecated_arguments do |keywords|
           keywords << :digits if legacy_digits != NOT_GIVEN
@@ -47,6 +51,8 @@ def leading_zero_number(legacy_digits = NOT_GIVEN, digits: 10)
       #
       # @example
       #   Faker::Number.decimal_part(digits: 2) #=> "09"
+      #
+      # @faker.version 1.0.0
       def decimal_part(legacy_digits = NOT_GIVEN, digits: 10)
         warn_for_deprecated_arguments do |keywords|
           keywords << :digits if legacy_digits != NOT_GIVEN
@@ -70,6 +76,8 @@ def decimal_part(legacy_digits = NOT_GIVEN, digits: 10)
       # @example
       #   Faker::Number.decimal(l_digits: 2) #=> 11.88
       #   Faker::Number.decimal(l_digits: 3, r_digits: 3) #=> 181.843
+      #
+      # @faker.version 1.0.0
       def decimal(legacy_l_digits = NOT_GIVEN, legacy_r_digits = NOT_GIVEN, l_digits: 5, r_digits: 2)
         warn_for_deprecated_arguments do |keywords|
           keywords << :l_digits if legacy_l_digits != NOT_GIVEN
@@ -94,6 +102,8 @@ def decimal(legacy_l_digits = NOT_GIVEN, legacy_r_digits = NOT_GIVEN, l_digits:
       #
       # @example
       #   Faker::Number.non_zero_digit #=> 8
+      #
+      # @faker.version 1.0.0
       def non_zero_digit
         rand(1..9)
       end
@@ -105,6 +115,8 @@ def non_zero_digit
       #
       # @example
       #   Faker::Number.digit #=> 1
+      #
+      # @faker.version 1.0.0
       def digit
         rand(10)
       end
@@ -117,6 +129,8 @@ def digit
       #
       # @example
       #   Faker::Number.hexadecimal(digits: 3) #=> "e74"
+      #
+      # @faker.version 1.0.0
       def hexadecimal(legacy_digits = NOT_GIVEN, digits: 6)
         warn_for_deprecated_arguments do |keywords|
           keywords << :digits if legacy_digits != NOT_GIVEN
@@ -136,6 +150,8 @@ def hexadecimal(legacy_digits = NOT_GIVEN, digits: 6)
       #
       # @example
       #   Faker::Number.normal(mean: 50, standard_deviation: 3.5) #=> 47.14669604069156
+      #
+      # @faker.version 1.0.0
       def normal(legacy_mean = NOT_GIVEN, legacy_standard_deviation = NOT_GIVEN, mean: 1, standard_deviation: 1)
         warn_for_deprecated_arguments do |keywords|
           keywords << :mean if legacy_mean != NOT_GIVEN
@@ -157,6 +173,8 @@ def normal(legacy_mean = NOT_GIVEN, legacy_standard_deviation = NOT_GIVEN, mean:
       #
       # @example
       #   Faker::Number.between(from: 1, to: 10) #=> 7
+      #
+      # @faker.version 1.0.0
       def between(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from: 1.00, to: 5000.00)
         warn_for_deprecated_arguments do |keywords|
           keywords << :from if legacy_from != NOT_GIVEN
@@ -174,6 +192,8 @@ def between(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from: 1.00, to: 5000
       #
       # @example
       #   Faker::Number.within(range: 1..10) #=> 7
+      #
+      # @faker.version 1.0.0
       def within(legacy_range = NOT_GIVEN, range: 1.00..5000.00)
         warn_for_deprecated_arguments do |keywords|
           keywords << :range if legacy_range != NOT_GIVEN
@@ -191,6 +211,8 @@ def within(legacy_range = NOT_GIVEN, range: 1.00..5000.00)
       #
       # @example
       #   Faker::Number.positive #=> 235.59238499107653
+      #
+      # @faker.version 1.0.0
       def positive(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from: 1.00, to: 5000.00)
         warn_for_deprecated_arguments do |keywords|
           keywords << :from if legacy_from != NOT_GIVEN
@@ -211,6 +233,8 @@ def positive(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from: 1.00, to: 500
       #
       # @example
       #   Faker::Number.negative #=> -4480.042585669558
+      #
+      # @faker.version 1.0.0
       def negative(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from: -5000.00, to: -1.00)
         warn_for_deprecated_arguments do |keywords|
           keywords << :from if legacy_from != NOT_GIVEN

lib/faker/default/time.rb

@@ -14,6 +14,7 @@ class Time < Base
 
     class << self
       # rubocop:disable Metrics/ParameterLists
+      # rubocop:disable Style/AsciiComments
 
       ##
       # Produce a random time between two times.
@@ -50,13 +51,14 @@ def between(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, legacy_format = NOT_
         time = Faker::Base.rand_in_range(from, to)
         time_with_format(time, format)
       end
+      # 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.
+      # @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]
       #
@@ -77,6 +79,8 @@ def between(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, legacy_format = NOT_
       #     #=> "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)
         warn_for_deprecated_arguments do |keywords|
           keywords << :from if legacy_from != NOT_GIVEN
@@ -94,7 +98,7 @@ def between_dates(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, legacy_period
       # 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.
+      # @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]
       #
@@ -119,7 +123,7 @@ def forward(legacy_days = NOT_GIVEN, legacy_period = NOT_GIVEN, legacy_format =
       # 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.
+      # @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]
       #