Skip to content

Commit

Permalink
Merge pull request faker-ruby#1753 from connorshea/add-even-more-yard…
Browse files Browse the repository at this point in the history 
…-docs

Add YARD docs for Date, Time, and Number
  • Loading branch information
@vbrazo
vbrazo committed Sep 22, 2019
2 parents 89dd36c + 21abb2f commit b24b21f
Show file tree
Hide file tree
Showing 3 changed files with 268 additions and 10 deletions.
61 changes: 59 additions & 2 deletions lib/faker/default/date.rb
View file
Expand Up @@ -3,6 +3,18 @@
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)
# #=> #<Date: 2014-09-24>
#
# @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
Expand All @@ -16,8 +28,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 to exclude.
# @return [Date]
#
# @example
# Faker::Date.between_except(from: 1.year.ago, to: 1.year.from_now, excepted: Date.today)
# #=> #<Date: 2014-10-03>
#
# @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 +62,18 @@ 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) #=> #<Date: 2014-10-03>
#
# @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
Expand All @@ -49,6 +85,16 @@ 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) #=> #<Date: 2019-09-12>
#
# @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
Expand All @@ -60,6 +106,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) #=> #<Date: 1986-03-28>
#
# @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
124 changes: 124 additions & 0 deletions lib/faker/default/number.rb
View file
Expand Up @@ -3,6 +3,16 @@
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
#
# @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
Expand All @@ -15,6 +25,16 @@ 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"
#
# @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
Expand All @@ -23,6 +43,16 @@ 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"
#
# @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
Expand All @@ -36,6 +66,18 @@ 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
#
# @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
Expand All @@ -53,14 +95,42 @@ 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
#
# @faker.version 1.0.0
def non_zero_digit
rand(1..9)
end

##
# Produces a single-digit integer.
#
# @return [Integer]
#
# @example
# Faker::Number.digit #=> 1
#
# @faker.version 1.0.0
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"
#
# @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
Expand All @@ -71,6 +141,17 @@ 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
#
# @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
Expand All @@ -83,6 +164,17 @@ 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
#
# @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
Expand All @@ -92,6 +184,16 @@ 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
#
# @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
Expand All @@ -100,6 +202,17 @@ 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
#
# @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
Expand All @@ -111,6 +224,17 @@ 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
#
# @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
Expand Down

0 comments on commit b24b21f

Please sign in to comment.