ruby-changes:54168
From: stomar <ko1@a...>
Date: Fri, 14 Dec 2018 07:41:48 +0900 (JST)
Subject: [ruby-changes:54168] stomar:r66389 (trunk): time.c: improve docs for Time
stomar 2018-12-14 07:41:44 +0900 (Fri, 14 Dec 2018) New Revision: 66389 https://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=revision&revision=66389 Log: time.c: improve docs for Time * time.c: [DOC] fix typos, drop unnecessary `p' from code examples, add missing `#' for return values, other small improvements. Modified files: trunk/time.c Index: time.c =================================================================== --- time.c (revision 66388) +++ time.c (revision 66389) @@ -2325,8 +2325,8 @@ time_init_1(int argc, VALUE *argv, VALUE https://github.com/ruby/ruby/blob/trunk/time.c#L2325 * *Note:* The new object will use the resolution available on your * system clock, and may include fractional seconds. * - * If one or more arguments specified, the time is initialized to the specified - * time. + * If one or more arguments are specified, the time is initialized to the + * specified time. * * +sec+ may have fraction if it is a rational. * @@ -2350,10 +2350,10 @@ time_init_1(int argc, VALUE *argv, VALUE https://github.com/ruby/ruby/blob/trunk/time.c#L2350 * t6 = Time.new(2007,11,5,11,21,0, "-05:00") # EST (Detroit) * t7 = Time.new(2007,11,5,13,45,0, "-05:00") # EST (Detroit) * t8 = Time.new(2007,11,6,17,10,0, "+09:00") # JST (Narita) - * p((t2-t1)/3600.0) #=> 10.666666666666666 - * p((t4-t3)/3600.0) #=> 2.466666666666667 - * p((t6-t5)/3600.0) #=> 1.95 - * p((t8-t7)/3600.0) #=> 13.416666666666666 + * (t2-t1)/3600.0 #=> 10.666666666666666 + * (t4-t3)/3600.0 #=> 2.466666666666667 + * (t6-t5)/3600.0 #=> 1.95 + * (t8-t7)/3600.0 #=> 13.416666666666666 * * Or it can be a timezone object. * See {Timezone argument}[#class-Time-label-Timezone+argument] for @@ -2695,7 +2695,7 @@ get_scale(VALUE unit) https://github.com/ruby/ruby/blob/trunk/time.c#L2695 * Time.at(-284061600) #=> 1960-12-31 00:00:00 -0600 * Time.at(946684800.2).usec #=> 200000 * Time.at(946684800, 123456.789).nsec #=> 123456789 - * Time.at(946684800, 123456789, :nsec).nsec #=> 123456789 + * Time.at(946684800, 123456789, :nsec).nsec #=> 123456789 */ static VALUE @@ -3436,7 +3436,7 @@ time_to_i(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L3436 * t.to_i #=> 1270968744 * * Note that IEEE 754 double is not accurate enough to represent - * the number of nanoseconds since the Epoch. + * the exact number of nanoseconds since the Epoch. */ static VALUE @@ -3456,7 +3456,7 @@ time_to_f(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L3456 * since the Epoch. * * t = Time.now - * p t.to_r #=> (1270968792716287611/1000000000) + * t.to_r #=> (1270968792716287611/1000000000) * * This methods is intended to be used to get an accurate value * representing the nanoseconds since the Epoch. You can use this method @@ -3559,7 +3559,7 @@ time_subsec(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L3559 /* * call-seq: - * time <=> other_time -> -1, 0, +1 or nil + * time <=> other_time -> -1, 0, +1, or nil * * Comparison---Compares +time+ with +other_time+. * @@ -3756,7 +3756,7 @@ time_zonelocal(VALUE time, VALUE off) https://github.com/ruby/ruby/blob/trunk/time.c#L3756 * t.localtime("+09:00") #=> 2000-01-02 05:15:01 +0900 * t.utc? #=> false * - * If +utc_offset+ is not given and _time_ is local time, just return + * If +utc_offset+ is not given and _time_ is local time, just returns * the receiver. */ @@ -3961,11 +3961,11 @@ time_asctime(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L3961 * #strftime with the appropriate format string. * * t = Time.now - * t.to_s => "2012-11-10 18:16:12 +0100" - * t.strftime "%Y-%m-%d %H:%M:%S %z" => "2012-11-10 18:16:12 +0100" + * t.to_s #=> "2012-11-10 18:16:12 +0100" + * t.strftime "%Y-%m-%d %H:%M:%S %z" #=> "2012-11-10 18:16:12 +0100" * - * t.utc.to_s => "2012-11-10 17:16:12 UTC" - * t.strftime "%Y-%m-%d %H:%M:%S UTC" => "2012-11-10 17:16:12 UTC" + * t.utc.to_s #=> "2012-11-10 17:16:12 UTC" + * t.strftime "%Y-%m-%d %H:%M:%S UTC" #=> "2012-11-10 17:16:12 UTC" */ static VALUE @@ -4096,35 +4096,35 @@ rb_time_succ(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L4096 * * Rounds sub seconds to a given precision in decimal digits (0 digits by default). * It returns a new Time object. - * +ndigits+ should be zero or positive integer. + * +ndigits+ should be zero or a positive integer. * * require 'time' * * t = Time.utc(2010,3,30, 5,43,"25.123456789".to_r) - * p t.iso8601(10) #=> "2010-03-30T05:43:25.1234567890Z" - * p t.round.iso8601(10) #=> "2010-03-30T05:43:25.0000000000Z" - * p t.round(0).iso8601(10) #=> "2010-03-30T05:43:25.0000000000Z" - * p t.round(1).iso8601(10) #=> "2010-03-30T05:43:25.1000000000Z" - * p t.round(2).iso8601(10) #=> "2010-03-30T05:43:25.1200000000Z" - * p t.round(3).iso8601(10) #=> "2010-03-30T05:43:25.1230000000Z" - * p t.round(4).iso8601(10) #=> "2010-03-30T05:43:25.1235000000Z" - * p t.round(5).iso8601(10) #=> "2010-03-30T05:43:25.1234600000Z" - * p t.round(6).iso8601(10) #=> "2010-03-30T05:43:25.1234570000Z" - * p t.round(7).iso8601(10) #=> "2010-03-30T05:43:25.1234568000Z" - * p t.round(8).iso8601(10) #=> "2010-03-30T05:43:25.1234567900Z" - * p t.round(9).iso8601(10) #=> "2010-03-30T05:43:25.1234567890Z" - * p t.round(10).iso8601(10) #=> "2010-03-30T05:43:25.1234567890Z" + * t.iso8601(10) #=> "2010-03-30T05:43:25.1234567890Z" + * t.round.iso8601(10) #=> "2010-03-30T05:43:25.0000000000Z" + * t.round(0).iso8601(10) #=> "2010-03-30T05:43:25.0000000000Z" + * t.round(1).iso8601(10) #=> "2010-03-30T05:43:25.1000000000Z" + * t.round(2).iso8601(10) #=> "2010-03-30T05:43:25.1200000000Z" + * t.round(3).iso8601(10) #=> "2010-03-30T05:43:25.1230000000Z" + * t.round(4).iso8601(10) #=> "2010-03-30T05:43:25.1235000000Z" + * t.round(5).iso8601(10) #=> "2010-03-30T05:43:25.1234600000Z" + * t.round(6).iso8601(10) #=> "2010-03-30T05:43:25.1234570000Z" + * t.round(7).iso8601(10) #=> "2010-03-30T05:43:25.1234568000Z" + * t.round(8).iso8601(10) #=> "2010-03-30T05:43:25.1234567900Z" + * t.round(9).iso8601(10) #=> "2010-03-30T05:43:25.1234567890Z" + * t.round(10).iso8601(10) #=> "2010-03-30T05:43:25.1234567890Z" * * t = Time.utc(1999,12,31, 23,59,59) - * p((t + 0.4).round.iso8601(3)) #=> "1999-12-31T23:59:59.000Z" - * p((t + 0.49).round.iso8601(3)) #=> "1999-12-31T23:59:59.000Z" - * p((t + 0.5).round.iso8601(3)) #=> "2000-01-01T00:00:00.000Z" - * p((t + 1.4).round.iso8601(3)) #=> "2000-01-01T00:00:00.000Z" - * p((t + 1.49).round.iso8601(3)) #=> "2000-01-01T00:00:00.000Z" - * p((t + 1.5).round.iso8601(3)) #=> "2000-01-01T00:00:01.000Z" + * (t + 0.4).round.iso8601(3) #=> "1999-12-31T23:59:59.000Z" + * (t + 0.49).round.iso8601(3) #=> "1999-12-31T23:59:59.000Z" + * (t + 0.5).round.iso8601(3) #=> "2000-01-01T00:00:00.000Z" + * (t + 1.4).round.iso8601(3) #=> "2000-01-01T00:00:00.000Z" + * (t + 1.49).round.iso8601(3) #=> "2000-01-01T00:00:00.000Z" + * (t + 1.5).round.iso8601(3) #=> "2000-01-01T00:00:01.000Z" * * t = Time.utc(1999,12,31, 23,59,59) - * p (t + 0.123456789).round(4).iso8601(6) #=> "1999-12-31T23:59:59.123500Z" + * (t + 0.123456789).round(4).iso8601(6) #=> "1999-12-31T23:59:59.123500Z" */ static VALUE @@ -4348,7 +4348,7 @@ time_sunday(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L4348 * Returns +true+ if _time_ represents Monday. * * t = Time.local(2003, 8, 4) #=> 2003-08-04 00:00:00 -0500 - * p t.monday? #=> true + * t.monday? #=> true */ static VALUE @@ -4364,7 +4364,7 @@ time_monday(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L4364 * Returns +true+ if _time_ represents Tuesday. * * t = Time.local(1991, 2, 19) #=> 1991-02-19 00:00:00 -0600 - * p t.tuesday? #=> true + * t.tuesday? #=> true */ static VALUE @@ -4380,7 +4380,7 @@ time_tuesday(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L4380 * Returns +true+ if _time_ represents Wednesday. * * t = Time.local(1993, 2, 24) #=> 1993-02-24 00:00:00 -0600 - * p t.wednesday? #=> true + * t.wednesday? #=> true */ static VALUE @@ -4396,7 +4396,7 @@ time_wednesday(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L4396 * Returns +true+ if _time_ represents Thursday. * * t = Time.local(1995, 12, 21) #=> 1995-12-21 00:00:00 -0600 - * p t.thursday? #=> true + * t.thursday? #=> true */ static VALUE @@ -4764,15 +4764,15 @@ strftime_cstr(const char *fmt, size_t le https://github.com/ruby/ruby/blob/trunk/time.c#L4764 * America/Havana (-05:00), Asia/Harbin (+08:00), Australia/Darwin (+09:30) * and Australia/Adelaide (+10:30). * Also, %Z is highly dependent on the operating system. - * For example, it may generate a non ASCII string on Japanese Windows. + * For example, it may generate a non ASCII string on Japanese Windows, * i.e. the result can be different to "JST". * So the numeric time zone offset, %z, is recommended. * * Examples: * * t = Time.new(2007,11,19,8,37,48,"-06:00") #=> 2007-11-19 08:37:48 -0600 - * t.strftime("Printed on %m/%d/%Y") #=> "Printed on 11/19/2007" - * t.strftime("at %I:%M%p") #=> "at 08:37AM" + * t.strftime("Printed on %m/%d/%Y") #=> "Printed on 11/19/2007" + * t.strftime("at %I:%M %p") #=> "at 08:37 AM" * * Various ISO 8601 formats: * %Y%m%d => 20071119 Calendar date (basic) @@ -5479,7 +5479,7 @@ rb_time_zone_abbreviation(VALUE zone, VA https://github.com/ruby/ruby/blob/trunk/time.c#L5479 * * The +name+ method is used for marshaling. If this method is not * defined on a timezone object, Time objects using that timezone - * object are not able to dump by Marshal. + * object can not be dumped by Marshal. * * The +abbr+ method is used by '%Z' in #strftime. * -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/