Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add YARD docs for Date, Time, and Number #1753

Merged
merged 6 commits into from Sep 22, 2019
Merged

Add YARD docs for Date, Time, and Number #1753

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
efc976f
Add YARD docs for Faker::Time.
connorshea Sep 19, 2019
d96fd63
Add YARD docs for Faker::Date.
connorshea Sep 19, 2019
cdbf06f
Oops, forgot return types for Date and Time.
connorshea Sep 19, 2019
5a2314c
Add YARD docs for Faker::Number.
connorshea Sep 19, 2019
711843b
Update some YARD docs to resolve feedback.
connorshea Sep 19, 2019
44efce8
Update returned date object in examples.
connorshea Sep 20, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
55 changes: 53 additions & 2 deletions lib/faker/default/date.rb
View file
Open in desktop
Expand Up @@ -3,6 +3,16 @@
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.
# @return [Date]
#
# @example
# Faker::Date.between(from: 2.days.ago, to: Date.today)
# #=> "Wed, 24 Sep 2014"
connorshea marked this conversation as resolved.
Show resolved Hide resolved
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
Expand All @@ -16,8 +26,21 @@ 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.
connorshea marked this conversation as resolved.
Show resolved Hide resolved
# @return [Date]
#
# @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
Expand All @@ -37,7 +60,16 @@ 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.
# @return [Date]
#
# @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
Expand All @@ -49,6 +81,14 @@ 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.
# @return [Date]
#
# @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
Expand All @@ -60,6 +100,17 @@ 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.
# @return [Date]
#
# @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
Expand Down
100 changes: 100 additions & 0 deletions lib/faker/default/number.rb
View file
Open in desktop
Expand Up @@ -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
connorshea marked this conversation as resolved.
Show resolved Hide resolved
def number(legacy_digits = NOT_GIVEN, digits: 10)
warn_for_deprecated_arguments do |keywords|
keywords << :digits if legacy_digits != NOT_GIVEN
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down
87 changes: 80 additions & 7 deletions lib/faker/default/time.rb
View file
Open in desktop
Expand Up @@ -14,8 +14,30 @@ 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.
# @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
Expand All @@ -29,9 +51,33 @@ 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.
connorshea marked this conversation as resolved.
Show resolved Hide resolved
# @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"
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
Expand All @@ -44,9 +90,22 @@ 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.
# @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
Expand All @@ -56,9 +115,22 @@ 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.
# @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
Expand All @@ -67,6 +139,7 @@ def backward(legacy_days = NOT_GIVEN, legacy_period = NOT_GIVEN, legacy_format =

time_with_format(date_with_random_time(Faker::Date.backward(days: days), period), format)
end
# rubocop:enable Metrics/ParameterLists

private

Expand Down