From ec39334cb8891a8f7440eef0311d2059a2421162 Mon Sep 17 00:00:00 2001 From: Connor Shea Date: Wed, 18 Sep 2019 18:59:13 -0600 Subject: [PATCH 1/6] Add YARD docs for Faker::Time. --- lib/faker/default/time.rb | 85 +++++++++++++++++++++++++++++++++++---- 1 file changed, 77 insertions(+), 8 deletions(-) diff --git a/lib/faker/default/time.rb b/lib/faker/default/time.rb index b96a5d5d81..628c49eb0c 100644 --- a/lib/faker/default/time.rb +++ b/lib/faker/default/time.rb @@ -14,8 +14,29 @@ class Time < Base class << self # rubocop:disable Metrics/ParameterLists + + ## + # 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. + # + # @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 @@ -29,9 +50,32 @@ def between(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, legacy_format = NOT_ time_with_format(time, format) end - # rubocop:disable Metrics/ParameterLists + ## + # 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 format [Symbol] The name of a DateTime format to use. + # + # @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" 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 +88,21 @@ def between_dates(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, legacy_period 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. + # @param format [Symbol] The name of a DateTime format to use. + # + # @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,17 +112,30 @@ def forward(legacy_days = NOT_GIVEN, legacy_period = NOT_GIVEN, legacy_format = 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. + # @param format [Symbol] The name of a DateTime format to use. + # + # @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 keywords << :format if legacy_format != NOT_GIVEN end - + time_with_format(date_with_random_time(Faker::Date.backward(days: days), period), format) end + # rubocop:enable Metrics/ParameterLists private From 04e36474380258cb2d49d0828a9128a93eef70d5 Mon Sep 17 00:00:00 2001 From: Connor Shea Date: Wed, 18 Sep 2019 19:08:58 -0600 Subject: [PATCH 2/6] Add YARD docs for Faker::Date. --- lib/faker/default/date.rb | 50 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 48 insertions(+), 2 deletions(-) diff --git a/lib/faker/default/date.rb b/lib/faker/default/date.rb index 8b3e16446b..e46adbf470 100644 --- a/lib/faker/default/date.rb +++ b/lib/faker/default/date.rb @@ -3,6 +3,15 @@ module Faker class Date < Base class << self + ## + # Produce a random date between two dates. + # + # @param from [Date] The start of the usable date range. + # @param to [Date] The end of the usable date range. + # + # @example + # Faker::Date.between(from: 2.days.ago, to: Date.today) + # #=> "Wed, 24 Sep 2014" 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 @@ -16,8 +25,20 @@ def between(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from:, to:) end # rubocop:disable Metrics/ParameterLists + + ## + # Produce a random date between two dates. + # + # @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. + # + # @example + # Faker::Date.between_except(from: 1.year.ago, to: 1.year.from_now, excepted: Date.today) + # #=> "Wed, 24 Sep 2014" + # + # @faker.version 1.6.2 def between_except(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, legacy_excepted = NOT_GIVEN, from:, to:, excepted:) - # rubocop:enable Metrics/ParameterLists warn_for_deprecated_arguments do |keywords| keywords << :from if legacy_from != NOT_GIVEN end @@ -37,7 +58,15 @@ def between_except(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, legacy_except break date.to_date if date != excepted end end - + # rubocop:enable Metrics/ParameterLists + + ## + # Produce a random date in the future (up to N days). + # + # @param days [Integer] The maximum number of days to go into the future. + # + # @example + # Faker::Date.forward(days: 23) # => "Fri, 03 Oct 2014" def forward(legacy_days = NOT_GIVEN, days: 365) warn_for_deprecated_arguments do |keywords| keywords << :days if legacy_days != NOT_GIVEN @@ -49,6 +78,13 @@ def forward(legacy_days = NOT_GIVEN, days: 365) between(from: from, to: to).to_date end + ## + # Produce a random date in the past (up to N days). + # + # @param days [Integer] The maximum number of days to go into the past. + # + # @example + # Faker::Date.backward(days: 14) #=> "Fri, 19 Sep 2014" def backward(legacy_days = NOT_GIVEN, days: 365) warn_for_deprecated_arguments do |keywords| keywords << :days if legacy_days != NOT_GIVEN @@ -60,6 +96,16 @@ def backward(legacy_days = NOT_GIVEN, days: 365) between(from: from, to: to).to_date end + ## + # Produce a random date in the past (up to N days). + # + # @param min_age [Integer] The minimum age that the birthday would imply. + # @param max_age [Integer] The maximum age that the birthday would imply. + # + # @example + # Faker::Date.birthday(min_age: 18, max_age: 65) #=> "28 Mar 1986" + # + # @faker.version 1.4.3 def birthday(legacy_min_age = NOT_GIVEN, legacy_max_age = NOT_GIVEN, min_age: 18, max_age: 65) warn_for_deprecated_arguments do |keywords| keywords << :min_age if legacy_min_age != NOT_GIVEN From 048c29b8cbe2e72ad8b5c14bee5e0ad96ee1ec76 Mon Sep 17 00:00:00 2001 From: Connor Shea Date: Wed, 18 Sep 2019 19:22:38 -0600 Subject: [PATCH 3/6] Oops, forgot return types for Date and Time. --- lib/faker/default/date.rb | 5 +++++ lib/faker/default/time.rb | 6 +++++- 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/lib/faker/default/date.rb b/lib/faker/default/date.rb index e46adbf470..481dc98197 100644 --- a/lib/faker/default/date.rb +++ b/lib/faker/default/date.rb @@ -8,6 +8,7 @@ class << self # # @param from [Date] The start of the usable date range. # @param to [Date] The end of the usable date range. + # @return [Date] # # @example # Faker::Date.between(from: 2.days.ago, to: Date.today) @@ -32,6 +33,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. + # @return [Date] # # @example # Faker::Date.between_except(from: 1.year.ago, to: 1.year.from_now, excepted: Date.today) @@ -64,6 +66,7 @@ def between_except(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, legacy_except # Produce a random date in the future (up to N days). # # @param days [Integer] The maximum number of days to go into the future. + # @return [Date] # # @example # Faker::Date.forward(days: 23) # => "Fri, 03 Oct 2014" @@ -82,6 +85,7 @@ def forward(legacy_days = NOT_GIVEN, days: 365) # Produce a random date in the past (up to N days). # # @param days [Integer] The maximum number of days to go into the past. + # @return [Date] # # @example # Faker::Date.backward(days: 14) #=> "Fri, 19 Sep 2014" @@ -101,6 +105,7 @@ def backward(legacy_days = NOT_GIVEN, days: 365) # # @param min_age [Integer] The minimum age that the birthday would imply. # @param max_age [Integer] The maximum age that the birthday would imply. + # @return [Date] # # @example # Faker::Date.birthday(min_age: 18, max_age: 65) #=> "28 Mar 1986" diff --git a/lib/faker/default/time.rb b/lib/faker/default/time.rb index 628c49eb0c..d781c34a93 100644 --- a/lib/faker/default/time.rb +++ b/lib/faker/default/time.rb @@ -21,6 +21,7 @@ class << self # @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 @@ -57,6 +58,7 @@ def between(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, legacy_format = NOT_ # @param to [Date] The end of the usable time range. # @param period [Symbol] The time of day, if any. # @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) @@ -94,6 +96,7 @@ def between_dates(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, legacy_period # @param days [Integer] The maximum number of days to go into the future. # @param period [Symbol] The time of day, if any. # @param format [Symbol] The name of a DateTime format to use. + # @return [Time] # # @example # Faker::Time.forward(days: 23, period: :morning) @@ -118,6 +121,7 @@ def forward(legacy_days = NOT_GIVEN, legacy_period = NOT_GIVEN, legacy_format = # @param days [Integer] The maximum number of days to go into the past. # @param period [Symbol] The time of day, if any. # @param format [Symbol] The name of a DateTime format to use. + # @return [Time] # # @example # Faker::Time.backward(days: 14, period: :evening) @@ -132,7 +136,7 @@ def backward(legacy_days = NOT_GIVEN, legacy_period = NOT_GIVEN, legacy_format = keywords << :period if legacy_period != NOT_GIVEN keywords << :format if legacy_format != NOT_GIVEN end - + time_with_format(date_with_random_time(Faker::Date.backward(days: days), period), format) end # rubocop:enable Metrics/ParameterLists From 22bd5b8a966bff60f7616c7a69757e7dc4d16a4e Mon Sep 17 00:00:00 2001 From: Connor Shea Date: Wed, 18 Sep 2019 19:30:37 -0600 Subject: [PATCH 4/6] Add YARD docs for Faker::Number. --- lib/faker/default/number.rb | 100 ++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) diff --git a/lib/faker/default/number.rb b/lib/faker/default/number.rb index 4e2ae78404..9e34fd20dd 100644 --- a/lib/faker/default/number.rb +++ b/lib/faker/default/number.rb @@ -3,6 +3,14 @@ module Faker class Number < Base class << self + ## + # Produce a random number. + # + # @param digits [Integer] Number of digits that the generated number should have. + # @return [Integer] + # + # @example + # Faker::Number.number(digits: 10) #=> 1968353479 def number(legacy_digits = NOT_GIVEN, digits: 10) warn_for_deprecated_arguments do |keywords| keywords << :digits if legacy_digits != NOT_GIVEN @@ -15,6 +23,14 @@ def number(legacy_digits = NOT_GIVEN, digits: 10) ([non_zero_digit] + generate(digits - 1)).join.to_i end + ## + # Produce a random number with a leading zero. + # + # @param digits [Integer] Number of digits that the generated number should have. + # @return [String] + # + # @example + # Faker::Number.leading_zero_number(digits: 10) #=> "0669336915" def leading_zero_number(legacy_digits = NOT_GIVEN, digits: 10) warn_for_deprecated_arguments do |keywords| keywords << :digits if legacy_digits != NOT_GIVEN @@ -23,6 +39,14 @@ def leading_zero_number(legacy_digits = NOT_GIVEN, digits: 10) '0' + (2..digits).collect { digit }.join end + ## + # Produce a number with a number of digits, preserves leading zeroes. + # + # @param digits [Integer] Number of digits that the generated number should have. + # @return [String] + # + # @example + # Faker::Number.decimal_part(digits: 2) #=> "09" def decimal_part(legacy_digits = NOT_GIVEN, digits: 10) warn_for_deprecated_arguments do |keywords| keywords << :digits if legacy_digits != NOT_GIVEN @@ -36,6 +60,16 @@ def decimal_part(legacy_digits = NOT_GIVEN, digits: 10) leading_zero_number(digits: digits) + num.to_s end + ## + # Produces a float. + # + # @param l_digits [Integer] Number of digits that the generated decimal should have to the left of the decimal point. + # @param r_digits [Integer] Number of digits that the generated decimal should have to the right of the decimal point. + # @return [Float] + # + # @example + # Faker::Number.decimal(l_digits: 2) #=> 11.88 + # Faker::Number.decimal(l_digits: 3, r_digits: 3) #=> 181.843 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 @@ -53,14 +87,36 @@ def decimal(legacy_l_digits = NOT_GIVEN, legacy_r_digits = NOT_GIVEN, l_digits: "#{l_d}.#{r_d}".to_f end + ## + # Produces a non-zero single-digit integer. + # + # @return [Integer] + # + # @example + # Faker::Number.non_zero_digit #=> 8 def non_zero_digit rand(1..9) end + ## + # Produces a single-digit integer. + # + # @return [Integer] + # + # @example + # Faker::Number.digit #=> 1 def digit rand(10) end + ## + # Produces a number in hexadecimal format. + # + # @param digits [Integer] Number of digits in the he + # @return [String] + # + # @example + # Faker::Number.hexadecimal(digits: 3) #=> "e74" def hexadecimal(legacy_digits = NOT_GIVEN, digits: 6) warn_for_deprecated_arguments do |keywords| keywords << :digits if legacy_digits != NOT_GIVEN @@ -71,6 +127,15 @@ def hexadecimal(legacy_digits = NOT_GIVEN, digits: 6) hex end + ## + # Produces a float given a mean and standard deviation. + # + # @param mean [Integer] + # @param standard_deviation [Integer, Float] + # @return [Float] + # + # @example + # Faker::Number.normal(mean: 50, standard_deviation: 3.5) #=> 47.14669604069156 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 @@ -83,6 +148,15 @@ def normal(legacy_mean = NOT_GIVEN, legacy_standard_deviation = NOT_GIVEN, mean: mean + scale * Math.cos(theta) end + ## + # Produces a number between two provided values. Boundaries are inclusive. + # + # @param from [Integer] The lowest number to include. + # @param to [Integer] The highest number to include. + # @return [Integer] + # + # @example + # Faker::Number.between(from: 1, to: 10) #=> 7 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 @@ -92,6 +166,14 @@ def between(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from: 1.00, to: 5000 Faker::Base.rand_in_range(from, to) end + ## + # Produces a number within two provided values. Boundaries are inclusive or exclusive depending on the range passed. + # + # @param range [Range] The range from which to generate a number. + # @return [Integer] + # + # @example + # Faker::Number.within(range: 1..10) #=> 7 def within(legacy_range = NOT_GIVEN, range: 1.00..5000.00) warn_for_deprecated_arguments do |keywords| keywords << :range if legacy_range != NOT_GIVEN @@ -100,6 +182,15 @@ def within(legacy_range = NOT_GIVEN, range: 1.00..5000.00) between(from: range.min, to: range.max) end + ## + # Produces a positive float. + # + # @param from [Integer] The lower boundary. + # @param to [Integer] The higher boundary. + # @return [Float] + # + # @example + # Faker::Number.positive #=> 235.59238499107653 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 @@ -111,6 +202,15 @@ def positive(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from: 1.00, to: 500 greater_than_zero(random_number) end + ## + # Produces a negative float. + # + # @param from [Integer] The lower boundary. + # @param to [Integer] The higher boundary. + # @return [Float] + # + # @example + # Faker::Number.negative #=> -4480.042585669558 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 From ade5a107e33adab17dd49be70bf1be8cb47734a0 Mon Sep 17 00:00:00 2001 From: Connor Shea Date: Thu, 19 Sep 2019 17:31:29 -0600 Subject: [PATCH 5/6] 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 | 8 +++++++- lib/faker/default/number.rb | 24 ++++++++++++++++++++++++ lib/faker/default/time.rb | 10 +++++++--- 3 files changed, 38 insertions(+), 4 deletions(-) diff --git a/lib/faker/default/date.rb b/lib/faker/default/date.rb index 481dc98197..df462c4827 100644 --- a/lib/faker/default/date.rb +++ b/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 diff --git a/lib/faker/default/number.rb b/lib/faker/default/number.rb index 9e34fd20dd..38230e0ec4 100644 --- a/lib/faker/default/number.rb +++ b/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 diff --git a/lib/faker/default/time.rb b/lib/faker/default/time.rb index d781c34a93..c8cf423520 100644 --- a/lib/faker/default/time.rb +++ b/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] # From 21abb2fe44457947d62223e1184aeae19c5f4bb3 Mon Sep 17 00:00:00 2001 From: Connor Shea Date: Thu, 19 Sep 2019 20:19:55 -0600 Subject: [PATCH 6/6] Update returned date object in examples. --- lib/faker/default/date.rb | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/lib/faker/default/date.rb b/lib/faker/default/date.rb index df462c4827..497815eb3f 100644 --- a/lib/faker/default/date.rb +++ b/lib/faker/default/date.rb @@ -12,7 +12,7 @@ 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:) @@ -39,7 +39,7 @@ def between(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from:, to:) # # @example # Faker::Date.between_except(from: 1.year.ago, to: 1.year.from_now, excepted: Date.today) - # #=> "Wed, 24 Sep 2014" + # #=> # # # @faker.version 1.6.2 def between_except(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, legacy_excepted = NOT_GIVEN, from:, to:, excepted:) @@ -71,7 +71,7 @@ def between_except(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, legacy_except # @return [Date] # # @example - # Faker::Date.forward(days: 23) # => "Fri, 03 Oct 2014" + # Faker::Date.forward(days: 23) #=> # # # @faker.version 1.0.0 def forward(legacy_days = NOT_GIVEN, days: 365) @@ -92,7 +92,7 @@ def forward(legacy_days = NOT_GIVEN, days: 365) # @return [Date] # # @example - # Faker::Date.backward(days: 14) #=> "Fri, 19 Sep 2014" + # Faker::Date.backward(days: 14) #=> # # # @faker.version 1.0.0 def backward(legacy_days = NOT_GIVEN, days: 365) @@ -114,7 +114,7 @@ def backward(legacy_days = NOT_GIVEN, days: 365) # @return [Date] # # @example - # Faker::Date.birthday(min_age: 18, max_age: 65) #=> "28 Mar 1986" + # Faker::Date.birthday(min_age: 18, max_age: 65) #=> # # # @faker.version 1.4.3 def birthday(legacy_min_age = NOT_GIVEN, legacy_max_age = NOT_GIVEN, min_age: 18, max_age: 65)