ruby-changes:45476
From: nobu <ko1@a...>
Date: Mon, 6 Feb 2017 16:34:22 +0900 (JST)
Subject: [ruby-changes:45476] nobu:r57549 (trunk): date_core.c: [DOC] revise docs [ci skip]
nobu 2017-02-06 16:34:13 +0900 (Mon, 06 Feb 2017) New Revision: 57549 https://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=revision&revision=57549 Log: date_core.c: [DOC] revise docs [ci skip] * fix malformed rdoc for Date#today, Date._strptime, and DateTime._strptime * add code examples for Date#<< and Date#>> to demonstrate that different dates can result in the same return value * use Date::ITALY in call-seq instead of only ITALY * fix some copy/paste mistakes where Date should be DateTime * fix various errors and grammar * fix cross references and formatting [ruby-core:79433] [Bug #13193] Author: Marcus Stollsteimer <sto.mar@w...> Modified files: trunk/ext/date/date_core.c Index: ext/date/date_core.c =================================================================== --- ext/date/date_core.c (revision 57548) +++ ext/date/date_core.c (revision 57549) @@ -2462,7 +2462,7 @@ date_s__valid_jd_p(int argc, VALUE *argv https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L2462 * * Date.valid_jd?(2451944) #=> true * - * See also jd. + * See also ::jd. */ static VALUE date_s_valid_jd_p(int argc, VALUE *argv, VALUE klass) @@ -2551,7 +2551,7 @@ date_s__valid_civil_p(int argc, VALUE *a https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L2551 * Date.valid_date?(2001,2,3) #=> true * Date.valid_date?(2001,2,29) #=> false * - * See also jd and civil. + * See also ::jd and ::civil. */ static VALUE date_s_valid_civil_p(int argc, VALUE *argv, VALUE klass) @@ -2632,7 +2632,7 @@ date_s__valid_ordinal_p(int argc, VALUE https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L2632 * Date.valid_ordinal?(2001,34) #=> true * Date.valid_ordinal?(2001,366) #=> false * - * See also jd and ordinal. + * See also ::jd and ::ordinal. */ static VALUE date_s_valid_ordinal_p(int argc, VALUE *argv, VALUE klass) @@ -2714,7 +2714,7 @@ date_s__valid_commercial_p(int argc, VAL https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L2714 * Date.valid_commercial?(2001,5,6) #=> true * Date.valid_commercial?(2001,5,8) #=> false * - * See also jd and commercial. + * See also ::jd and ::commercial. */ static VALUE date_s_valid_commercial_p(int argc, VALUE *argv, VALUE klass) @@ -3262,7 +3262,7 @@ static VALUE d_lite_plus(VALUE, VALUE); https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L3262 * Date.jd(2451945) #=> #<Date: 2001-02-04 ...> * Date.jd(0) #=> #<Date: -4712-01-01 ...> * - * See also new. + * See also ::new. */ static VALUE date_s_jd(int argc, VALUE *argv, VALUE klass) @@ -3312,7 +3312,7 @@ date_s_jd(int argc, VALUE *argv, VALUE k https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L3312 * Date.ordinal(2001,34) #=> #<Date: 2001-02-03 ...> * Date.ordinal(2001,-1) #=> #<Date: 2001-12-31 ...> * - * See also jd and new. + * See also ::jd and ::new. */ static VALUE date_s_ordinal(int argc, VALUE *argv, VALUE klass) @@ -3380,7 +3380,7 @@ date_s_ordinal(int argc, VALUE *argv, VA https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L3380 * Date.new(2001,2,3) #=> #<Date: 2001-02-03 ...> * Date.new(2001,2,-1) #=> #<Date: 2001-02-28 ...> * - * See also jd. + * See also ::jd. */ static VALUE date_s_civil(int argc, VALUE *argv, VALUE klass) @@ -3457,7 +3457,7 @@ date_s_civil(int argc, VALUE *argv, VALU https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L3457 * Date.commercial(2002) #=> #<Date: 2001-12-31 ...> * Date.commercial(2001,5,6) #=> #<Date: 2001-02-03 ...> * - * See also jd and new. + * See also ::jd and ::new. */ static VALUE date_s_commercial(int argc, VALUE *argv, VALUE klass) @@ -3631,9 +3631,9 @@ static void set_sg(union DateData *, dou https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L3631 * call-seq: * Date.today([start=Date::ITALY]) -> date * - * Date.today #=> #<Date: 2011-06-11 ..> - * * Creates a date object denoting the present day. + * + * Date.today #=> #<Date: 2011-06-11 ...> */ static VALUE date_s_today(int argc, VALUE *argv, VALUE klass) @@ -4236,7 +4236,7 @@ date_s__strptime_internal(int argc, VALU https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4236 * Date._strptime('2001-02-03', '%Y-%m-%d') * #=> {:year=>2001, :mon=>2, :mday=>3} * - * See also strptime(3) and strftime. + * See also strptime(3) and #strftime. */ static VALUE date_s__strptime(int argc, VALUE *argv, VALUE klass) @@ -4246,7 +4246,7 @@ date_s__strptime(int argc, VALUE *argv, https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4246 /* * call-seq: - * Date.strptime([string='-4712-01-01'[, format='%F'[, start=ITALY]]]) -> date + * Date.strptime([string='-4712-01-01'[, format='%F'[, start=Date::ITALY]]]) -> date * * Parses the given representation of date and time with the given * template, and creates a date object. strptime does not support @@ -4260,7 +4260,7 @@ date_s__strptime(int argc, VALUE *argv, https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4260 * Date.strptime('2001 05 6', '%Y %W %u') #=> #<Date: 2001-02-03 ...> * Date.strptime('sat3feb01', '%a%d%b%y') #=> #<Date: 2001-02-03 ...> * - * See also strptime(3) and strftime. + * See also strptime(3) and #strftime. */ static VALUE date_s_strptime(int argc, VALUE *argv, VALUE klass) @@ -4340,7 +4340,7 @@ date_s__parse(int argc, VALUE *argv, VAL https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4340 /* * call-seq: - * Date.parse(string='-4712-01-01'[, comp=true[, start=ITALY]]) -> date + * Date.parse(string='-4712-01-01'[, comp=true[, start=Date::ITALY]]) -> date * * Parses the given representation of date and time, and creates a * date object. This method does not function as a validator. @@ -4400,7 +4400,7 @@ date_s__iso8601(VALUE klass, VALUE str) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4400 /* * call-seq: - * Date.iso8601(string='-4712-01-01'[, start=ITALY]) -> date + * Date.iso8601(string='-4712-01-01'[, start=Date::ITALY]) -> date * * Creates a new Date object by parsing from a string according to * some typical ISO 8601 formats. @@ -4443,7 +4443,7 @@ date_s__rfc3339(VALUE klass, VALUE str) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4443 /* * call-seq: - * Date.rfc3339(string='-4712-01-01T00:00:00+00:00'[, start=ITALY]) -> date + * Date.rfc3339(string='-4712-01-01T00:00:00+00:00'[, start=Date::ITALY]) -> date * * Creates a new Date object by parsing from a string according to * some typical RFC 3339 formats. @@ -4484,7 +4484,7 @@ date_s__xmlschema(VALUE klass, VALUE str https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4484 /* * call-seq: - * Date.xmlschema(string='-4712-01-01'[, start=ITALY]) -> date + * Date.xmlschema(string='-4712-01-01'[, start=Date::ITALY]) -> date * * Creates a new Date object by parsing from a string according to * some typical XML Schema formats. @@ -4526,8 +4526,8 @@ date_s__rfc2822(VALUE klass, VALUE str) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4526 /* * call-seq: - * Date.rfc2822(string='Mon, 1 Jan -4712 00:00:00 +0000'[, start=ITALY]) -> date - * Date.rfc822(string='Mon, 1 Jan -4712 00:00:00 +0000'[, start=ITALY]) -> date + * Date.rfc2822(string='Mon, 1 Jan -4712 00:00:00 +0000'[, start=Date::ITALY]) -> date + * Date.rfc822(string='Mon, 1 Jan -4712 00:00:00 +0000'[, start=Date::ITALY]) -> date * * Creates a new Date object by parsing from a string according to * some typical RFC 2822 formats. @@ -4569,7 +4569,7 @@ date_s__httpdate(VALUE klass, VALUE str) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4569 /* * call-seq: - * Date.httpdate(string='Mon, 01 Jan -4712 00:00:00 GMT'[, start=ITALY]) -> date + * Date.httpdate(string='Mon, 01 Jan -4712 00:00:00 GMT'[, start=Date::ITALY]) -> date * * Creates a new Date object by parsing from a string according to * some RFC 2616 format. @@ -4611,7 +4611,7 @@ date_s__jisx0301(VALUE klass, VALUE str) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L4611 /* * call-seq: - * Date.jisx0301(string='-4712-01-01'[, start=ITALY]) -> date + * Date.jisx0301(string='-4712-01-01'[, start=Date::ITALY]) -> date * * Creates a new Date object by parsing from a string according to * some typical JIS X 0301 formats. @@ -5380,7 +5380,7 @@ dup_obj_with_new_start(VALUE obj, double https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L5380 * call-seq: * d.new_start([start=Date::ITALY]) -> date * - * Duplicates self and resets its the day of calendar reform. + * Duplicates self and resets its day of calendar reform. * * d = Date.new(1582,10,15) * d.new_start(Date::JULIAN) #=> #<Date: 1582-10-05 ...> @@ -5498,9 +5498,9 @@ d_lite_new_offset(int argc, VALUE *argv, https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L5498 * call-seq: * d + other -> date * - * Returns a date object pointing other days after self. The other - * should be a numeric value. If the other is flonum, assumes its - * precision is at most nanosecond. + * Returns a date object pointing +other+ days after self. The other + * should be a numeric value. If the other is a fractional number, + * assumes its precision is at most nanosecond. * * Date.new(2001,2,3) + 1 #=> #<Date: 2001-02-04 ...> * DateTime.new(2001,2,3) + Rational(1,2) @@ -5883,8 +5883,8 @@ minus_dd(VALUE self, VALUE other) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L5883 * * Returns the difference between the two dates if the other is a date * object. If the other is a numeric value, returns a date object - * pointing other days before self. If the other is flonum, assumes - * its precision is at most nanosecond. + * pointing +other+ days before self. If the other is a fractional number, + * assumes its precision is at most nanosecond. * * Date.new(2001,2,3) - 1 #=> #<Date: 2001-02-02 ...> * DateTime.new(2001,2,3) - Rational(1,2) @@ -5965,12 +5965,13 @@ d_lite_next(VALUE self) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L5965 * call-seq: * d >> n -> date * - * Returns a date object pointing n months after self. The n should - * be a numeric value. + * Returns a date object pointing +n+ months after self. + * The argument +n+ should be a numeric value. * - * Date.new(2001,2,3) >> 1 #=> #<Date: 2001-03-03 ...> - * Date.new(2001,1,31) >> 1 #=> #<Date: 2001-02-28 ...> - * Date.new(2001,2,3) >> -2 #=> #<Date: 2000-12-03 ...> + * Date.new(2001,2,3) >> 1 #=> #<Date: 2001-03-03 ...> + * Date.new(2001,1,30) >> 1 #=> #<Date: 2001-02-28 ...> + * Date.new(2001,1,31) >> 1 #=> #<Date: 2001-02-28 ...> + * Date.new(2001,2,3) >> -2 #=> #<Date: 2000-12-03 ...> */ static VALUE d_lite_rshift(VALUE self, VALUE other) @@ -6015,12 +6016,13 @@ d_lite_rshift(VALUE self, VALUE other) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L6016 * call-seq: * d << n -> date * - * Returns a date object pointing n months before self. The n should - * be a numeric value. + * Returns a date object pointing +n+ months before self. + * The argument +n+ should be a numeric value. * - * Date.new(2001,2,3) << 1 #=> #<Date: 2001-01-03 ...> - * Date.new(2001,1,31) << 11 #=> #<Date: 2000-02-29 ...> - * Date.new(2001,2,3) << -1 #=> #<Date: 2001-03-03 ...> + * Date.new(2001,2,3) << 1 #=> #<Date: 2001-01-03 ...> + * Date.new(2001,1,30) << 11 #=> #<Date: 2000-02-29 ...> + * Date.new(2001,1,31) << 11 #=> #<Date: 2000-02-29 ...> + * Date.new(2001,2,3) << -1 #=> #<Date: 2001-03-03 ...> */ static VALUE d_lite_lshift(VALUE self, VALUE other) @@ -6033,7 +6035,7 @@ d_lite_lshift(VALUE self, VALUE other) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L6035 * call-seq: * d.next_month([n=1]) -> date * - * This method is equivalent to d >> n + * This method is equivalent to d >> n. */ static VALUE d_lite_next_month(int argc, VALUE *argv, VALUE self) @@ -6050,7 +6052,7 @@ d_lite_next_month(int argc, VALUE *argv, https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L6052 * call-seq: * d.prev_month([n=1]) -> date * - * This method is equivalent to d << n + * This method is equivalent to d << n. */ static VALUE d_lite_prev_month(int argc, VALUE *argv, VALUE self) @@ -6067,7 +6069,7 @@ d_lite_prev_month(int argc, VALUE *argv, https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L6069 * call-seq: * d.next_year([n=1]) -> date * - * This method is equivalent to d >> (n * 12) + * This method is equivalent to d >> (n * 12). */ static VALUE d_lite_next_year(int argc, VALUE *argv, VALUE self) @@ -6084,7 +6086,7 @@ d_lite_next_year(int argc, VALUE *argv, https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L6086 * call-seq: * d.prev_year([n=1]) -> date * - * This method is equivalent to d << (n * 12) + * This method is equivalent to d << (n * 12). */ static VALUE d_lite_prev_year(int argc, VALUE *argv, VALUE self) @@ -6272,11 +6274,11 @@ cmp_dd(VALUE self, VALUE other) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L6274 * should be a date object or a numeric value as an astronomical * Julian day number. * - * Date.new(2001,2,3) <=> Date.new(2001,2,4) #=> -1 - * Date.new(2001,2,3) <=> Date.new(2001,2,3) #=> 0 - * Date.new(2001,2,3) <=> Date.new(2001,2,2) #=> 1 - * Date.new(2001,2,3) <=> Object.new #=> nil - * Date.new(2001,2,3) <=> Rational(4903887,2)#=> 0 + * Date.new(2001,2,3) <=> Date.new(2001,2,4) #=> -1 + * Date.new(2001,2,3) <=> Date.new(2001,2,3) #=> 0 + * Date.new(2001,2,3) <=> Date.new(2001,2,2) #=> 1 + * Date.new(2001,2,3) <=> Object.new #=> nil + * Date.new(2001,2,3) <=> Rational(4903887,2) #=> 0 * * See also Comparable. */ @@ -6416,8 +6418,8 @@ static VALUE strftimev(const char *, VAL https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L6418 * call-seq: * d.to_s -> string * - * Returns a string in an ISO 8601 format (This method doesn't use the - * expanded representations). + * Returns a string in an ISO 8601 format. (This method doesn't use the + * expanded representations.) * * Date.new(2001,2,3).to_s #=> "2001-02-03" */ @@ -6691,7 +6693,7 @@ date_strftime_internal(int argc, VALUE * https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L6693 * * Formats date according to the directives in the given format * string. - * The directives begins with a percent (%) character. + * The directives begin with a percent (%) character. * Any text not listed as a directive will be passed through to the * output string. * @@ -6807,11 +6809,12 @@ date_strftime_internal(int argc, VALUE * https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L6809 * %T - 24-hour time (%H:%M:%S) * %+ - date(1) (%a %b %e %H:%M:%S %Z %Y) * - * This method is similar to strftime() function defined in ISO C and POSIX. + * This method is similar to the strftime() function defined in ISO C + * and POSIX. * Several directives (%a, %A, %b, %B, %c, %p, %r, %x, %X, %E*, %O* and %Z) * are locale dependent in the function. - * However this method is locale independent. - * So, the result may differ even if a same format string is used in other + * However, this method is locale independent. + * So, the result may differ even if the same format string is used in other * systems such as C. * It is good practice to avoid %x and %X because there are corresponding * locale independent representations, %D and %T. @@ -6859,7 +6862,7 @@ date_strftime_internal(int argc, VALUE * https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L6862 * %GW%V%uT%H%M%z => 2007W471T0837-0600 Week date and local time and difference from UTC (basic) * %G-W%V-%uT%R%:z => 2007-W47-1T08:37-06:00 Week date and local time and difference from UTC (extended) * - * See also strftime(3) and strptime. + * See also strftime(3) and ::strptime. */ static VALUE d_lite_strftime(int argc, VALUE *argv, VALUE self) @@ -7161,7 +7164,7 @@ date_s__load(VALUE klass, VALUE s) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L7164 * call-seq: * DateTime.jd([jd=0[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]) -> datetime * - * Creates a datetime object denoting the given chronological Julian + * Creates a DateTime object denoting the given chronological Julian * day number. * * DateTime.jd(2451944) #=> #<DateTime: 2001-02-03T00:00:00+00:00 ...> @@ -7229,7 +7232,7 @@ datetime_s_jd(int argc, VALUE *argv, VAL https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L7232 * call-seq: * DateTime.ordinal([year=-4712[, yday=1[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]]) -> datetime * - * Creates a date-time object denoting the given ordinal date. + * Creates a DateTime object denoting the given ordinal date. * * DateTime.ordinal(2001,34) #=> #<DateTime: 2001-02-03T00:00:00+00:00 ...> * DateTime.ordinal(2001,34,4,5,6,'+7') @@ -7305,7 +7308,7 @@ datetime_s_ordinal(int argc, VALUE *argv https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L7308 * DateTime.civil([year=-4712[, month=1[, mday=1[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]]]) -> datetime * DateTime.new([year=-4712[, month=1[, mday=1[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]]]) -> datetime * - * Creates a date-time object denoting the given calendar date. + * Creates a DateTime object denoting the given calendar date. * * DateTime.new(2001,2,3) #=> #<DateTime: 2001-02-03T00:00:00+00:00 ...> * DateTime.new(2001,2,3,4,5,6,'+7') @@ -7403,7 +7406,7 @@ datetime_s_civil(int argc, VALUE *argv, https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L7406 * call-seq: * DateTime.commercial([cwyear=-4712[, cweek=1[, cwday=1[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]]]) -> datetime * - * Creates a date-time object denoting the given week date. + * Creates a DateTime object denoting the given week date. * * DateTime.commercial(2001) #=> #<DateTime: 2001-01-01T00:00:00+00:00 ...> * DateTime.commercial(2002) #=> #<DateTime: 2001-12-31T00:00:00+00:00 ...> @@ -7620,7 +7623,7 @@ datetime_s_nth_kday(int argc, VALUE *arg https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L7623 * call-seq: * DateTime.now([start=Date::ITALY]) -> datetime * - * Creates a date-time object denoting the present time. + * Creates a DateTime object denoting the present time. * * DateTime.now #=> #<DateTime: 2011-06-11T21:20:44+09:00 ...> */ @@ -7823,7 +7826,7 @@ dt_new_by_frags(VALUE klass, VALUE hash, https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L7826 * template, and returns a hash of parsed elements. _strptime does * not support specification of flags and width unlike strftime. * - * See also strptime(3) and strftime. + * See also strptime(3) and #strftime. */ static VALUE datetime_s__strptime(int argc, VALUE *argv, VALUE klass) @@ -7833,10 +7836,10 @@ datetime_s__strptime(int argc, VALUE *ar https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L7836 /* * call-seq: - * DateTime.strptime([string='-4712-01-01T00:00:00+00:00'[, format='%FT%T%z'[ ,start=ITALY]]]) -> datetime + * DateTime.strptime([string='-4712-01-01T00:00:00+00:00'[, format='%FT%T%z'[ ,start=Date::ITALY]]]) -> datetime * * Parses the given representation of date and time with the given - * template, and creates a date object. strptime does not support + * template, and creates a DateTime object. strptime does not support * specification of flags and width unlike strftime. * * DateTime.strptime('2001-02-03T04:05:06+07:00', '%Y-%m-%dT%H:%M:%S%z') @@ -7856,7 +7859,7 @@ datetime_s__strptime(int argc, VALUE *ar https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L7859 * DateTime.strptime('sat3feb014pm+7', '%a%d%b%y%H%p%z') * #=> #<DateTime: 2001-02-03T16:00:00+07:00 ...> * - * See also strptime(3) and strftime. + * See also strptime(3) and #strftime. */ static VALUE datetime_s_strptime(int argc, VALUE *argv, VALUE klass) @@ -7886,10 +7889,10 @@ datetime_s_strptime(int argc, VALUE *arg https://github.com/ruby/ruby/blob/trunk/ext/dat (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/