ruby-changes:72415
From: BurdetteLamar <ko1@a...>
Date: Tue, 5 Jul 2022 04:13:06 +0900 (JST)
Subject: [ruby-changes:72415] 6324aaf3d0 (master): [ruby/date] Enhanced RDoc
https://git.ruby-lang.org/ruby.git/commit/?id=6324aaf3d0 From 6324aaf3d003d96be6b779a9cd92efd6fad70457 Mon Sep 17 00:00:00 2001 From: BurdetteLamar <BurdetteLamar@Y...> Date: Sun, 3 Jul 2022 08:38:05 -0500 Subject: [ruby/date] Enhanced RDoc https://github.com/ruby/date/commit/e80fee4f30 --- ext/date/date_core.c | 591 +++++++++++++++------------------------------------ 1 file changed, 169 insertions(+), 422 deletions(-) diff --git a/ext/date/date_core.c b/ext/date/date_core.c index c7b4459c89..87732f0d46 100644 --- a/ext/date/date_core.c +++ b/ext/date/date_core.c @@ -2466,13 +2466,13 @@ date_s__valid_jd_p(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L2466 /* * call-seq: - * Date.valid_jd?(jd[, start=Date::ITALY]) -> bool + * Date.valid_jd?(jd, start = Date::ITALY) -> true * - * Just returns true. It's nonsense, but is for symmetry. + * Returns +true+; implemented for compatibility. * - * Date.valid_jd?(2451944) #=> true + * Date.valid_jd?(2451944) # => true * - * See also ::jd. + * Related: Date.jd. */ static VALUE date_s_valid_jd_p(int argc, VALUE *argv, VALUE klass) @@ -2554,18 +2554,20 @@ date_s__valid_civil_p(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L2554 /* * call-seq: - * Date.valid_civil?(year, month, mday[, start=Date::ITALY]) -> bool - * Date.valid_date?(year, month, mday[, start=Date::ITALY]) -> bool + * Date.valid_civil?(year, month, mday, start = Date::ITALY) -> true or false * - * Returns true if the given calendar date is valid, and false if not. - * Valid in this context is whether the arguments passed to this - * method would be accepted by ::new. + * Returns +true+ if the arguments define a valid ordinal date, + * +false+ otherwise: * - * Date.valid_date?(2001,2,3) #=> true - * Date.valid_date?(2001,2,29) #=> false - * Date.valid_date?(2001,2,-1) #=> true + * Date.valid_date?(2001, 2, 3) # => true + * Date.valid_date?(2001, 2, 29) # => false + * Date.valid_date?(2001, 2, -1) # => true * - * See also ::jd and ::civil. + * See {Argument start}[rdoc-ref:Date@Argument+start]. + * + * Date.valid_date? is an alias for Date.valid_civil?. + * + * Related: Date.jd, Date.civil. */ static VALUE date_s_valid_civil_p(int argc, VALUE *argv, VALUE klass) @@ -2642,14 +2644,17 @@ date_s__valid_ordinal_p(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L2644 /* * call-seq: - * Date.valid_ordinal?(year, yday[, start=Date::ITALY]) -> bool + * Date.valid_ordinal?(year, yday, start = Date::ITALY) -> true or false * - * Returns true if the given ordinal date is valid, and false if not. + * Returns +true+ if the arguments define a valid ordinal date, + * +false+ otherwise: * - * Date.valid_ordinal?(2001,34) #=> true - * Date.valid_ordinal?(2001,366) #=> false + * Date.valid_ordinal?(2001, 34) # => true + * Date.valid_ordinal?(2001, 366) # => false * - * See also ::jd and ::ordinal. + * See {Argument start}[rdoc-ref:Date@Argument+start]. + * + * Related: Date.jd, Date.ordinal. */ static VALUE date_s_valid_ordinal_p(int argc, VALUE *argv, VALUE klass) @@ -2726,14 +2731,17 @@ date_s__valid_commercial_p(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L2731 /* * call-seq: - * Date.valid_commercial?(cwyear, cweek, cwday[, start=Date::ITALY]) -> bool + * Date.valid_commercial?(year, week, day, start = Date::ITALY) -> true or false + * + * Returns +true+ if the arguments define a valid commercial date, + * +false+ otherwise: * - * Returns true if the given week date is valid, and false if not. + * Date.valid_commercial?(2001, 5, 6) # => true + * Date.valid_commercial?(2001, 5, 8) # => false * - * Date.valid_commercial?(2001,5,6) #=> true - * Date.valid_commercial?(2001,5,8) #=> false + * See {Argument start}[rdoc-ref:Date@Argument+start]. * - * See also ::jd and ::commercial. + * Related: Date.jd, Date.commercial. */ static VALUE date_s_valid_commercial_p(int argc, VALUE *argv, VALUE klass) @@ -2913,13 +2921,15 @@ date_s_zone_to_diff(VALUE klass, VALUE str) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L2921 /* * call-seq: - * Date.julian_leap?(year) -> bool + * Date.julian_leap?(year) -> true or false * - * Returns true if the given year is a leap year of the proleptic - * Julian calendar. + * Returns +true+ if the given year is a leap year + * in the {proleptic Julian calendar}[https://en.wikipedia.org/wiki/Proleptic_Julian_calendar], +false+ otherwise: * - * Date.julian_leap?(1900) #=> true - * Date.julian_leap?(1901) #=> false + * Date.julian_leap?(1900) # => true + * Date.julian_leap?(1901) # => false + * + * Related: Date.gregorian_leap?. */ static VALUE date_s_julian_leap_p(VALUE klass, VALUE y) @@ -2934,14 +2944,17 @@ date_s_julian_leap_p(VALUE klass, VALUE y) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L2944 /* * call-seq: - * Date.gregorian_leap?(year) -> bool - * Date.leap?(year) -> bool + * Date.leap?(year) -> bool + * + * Returns +true+ if the given year is a leap year + * in the {proleptic Gregorian calendar}[https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar], +false+ otherwise: + * + * Date.gregorian_leap?(2000) # => true + * Date.gregorian_leap?(2001) # => false * - * Returns true if the given year is a leap year of the proleptic - * Gregorian calendar. + * Date.leap? is an alias for Date.gregorian_leap?. * - * Date.gregorian_leap?(1900) #=> false - * Date.gregorian_leap?(2000) #=> true + * Related: Date.julian_leap?. */ static VALUE date_s_gregorian_leap_p(VALUE klass, VALUE y) @@ -3281,16 +3294,17 @@ static VALUE d_lite_plus(VALUE, VALUE); https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L3294 /* * call-seq: - * Date.jd([jd=0[, start=Date::ITALY]]) -> date + * Date.jd(jd = 0, start = Date::ITALY) -> date * - * Creates a date object denoting the given chronological Julian day - * number. + * Returns a new \Date object formed from the arguments: * - * Date.jd(2451944) #=> #<Date: 2001-02-03 ...> - * Date.jd(2451945) #=> #<Date: 2001-02-04 ...> - * Date.jd(0) #=> #<Date: -4712-01-01 ...> + * Date.jd(2451944).to_s # => "2001-02-03" + * Date.jd(2451945).to_s # => "2001-02-04" + * Date.jd(0).to_s # => "-4712-01-01" * - * See also ::new. + * See {Argument start}[rdoc-ref:Date@Argument+start]. + * + * Related: Date.new. */ static VALUE date_s_jd(int argc, VALUE *argv, VALUE klass) @@ -3329,19 +3343,33 @@ date_s_jd(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L3343 /* * call-seq: - * Date.ordinal([year=-4712[, yday=1[, start=Date::ITALY]]]) -> date + * Date.ordinal(year = -4712, yday = 1, start = Date::ITALY) -> date * - * Creates a date object denoting the given ordinal date. + * Returns a new \Date object formed fom the arguments. * - * The day of year should be a negative or a positive number (as a - * relative day from the end of year when negative). It should not be - * zero. + * With no arguments, returns the date for January 1, -4712: * - * Date.ordinal(2001) #=> #<Date: 2001-01-01 ...> - * Date.ordinal(2001,34) #=> #<Date: 2001-02-03 ...> - * Date.ordinal(2001,-1) #=> #<Date: 2001-12-31 ...> + * Date.ordinal.to_s # => "-4712-01-01" * - * See also ::jd and ::new. + * With argument +year+, returns the date for January 1 of that year: + * + * Date.ordinal(2001).to_s # => "2001-01-01" + * Date.ordinal(-2001).to_s # => "-2001-01-01" + * + * With positive argument +yday+ == +n+, + * returns the date for the +nth+ day of the given year: + * + * Date.ordinal(2001, 14).to_s # => "2001-01-14" + * + * With negative argument +yday+, counts backward from the end of the year: + * + * Date.ordinal(2001, -14).to_s # => "2001-12-18" + * + * Raises an exception if +yday+ is zero or out of range. + * + * See {Argument start}[rdoc-ref:Date@Argument+start]. + * + * Related: Date.jd, Date.new. */ static VALUE date_s_ordinal(int argc, VALUE *argv, VALUE klass) @@ -3388,37 +3416,37 @@ date_s_ordinal(int argc, VALUE *argv, VALUE klass) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L3416 return ret; } +static VALUE +date_s_civil(int argc, VALUE *argv, VALUE klass) +{ + return date_initialize(argc, argv, d_lite_s_alloc_simple(klass)); +} + /* * call-seq: - * Date.civil([year=-4712[, month=1[, mday=1[, start=Date::ITALY]]]]) -> date - * Date.new([year=-4712[, month=1[, mday=1[, start=Date::ITALY]]]]) -> date + * Date.new(year = -4712, month = 1, mday = 1, start = Date::ITALY) -> date + * + * Returns a new \Date object constructed from the given arguments: * - * Creates a date object denoting the given calendar date. + * Date.new(2022).to_s # => "2022-01-01" + * Date.new(2022, 2).to_s # => "2022-02-01" + * Date.new(2022, 2, 4).to_s # => "2022-02-04" * - * In this class, BCE years are counted astronomically. Thus, the - * year before the year 1 is the year zero, and the year preceding the - * year zero is the year -1. The month and the day of month should be - * a negative or a positive number (as a relative month/day from the - * end of year/month when negative). They should not be zero. + * Argument +month+ should be in range (1..12) or range (-12..-1); + * when the argument is negative, counts backward from the end of the year: * - * The last argument should be a Julian day number which denotes the - * day of calendar reform. Date::ITALY (2299161=1582-10-15), - * Date::ENGLAND (2361222=1752-09-14), Date::GREGORIAN (the proleptic - * Gregorian calendar) and Date::JULIAN (the proleptic Julian - * calendar) can be specified as a day of calendar reform. + * Date.new(2022, -11, 4).to_s # => "2022 (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/