ruby-changes:25975
From: zzak <ko1@a...>
Date: Fri, 30 Nov 2012 13:53:25 +0900 (JST)
Subject: [ruby-changes:25975] zzak:r38032 (trunk): * time.c: Documentation improvements, grammar and formatting
zzak 2012-11-30 13:53:09 +0900 (Fri, 30 Nov 2012) New Revision: 38032 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=38032 Log: * time.c: Documentation improvements, grammar and formatting Patch by Bernd Homuth [ruby-core:49203] [Bug #7326] Modified files: trunk/ChangeLog trunk/time.c Index: time.c =================================================================== --- time.c (revision 38031) +++ time.c (revision 38032) @@ -1399,12 +1399,12 @@ static struct tm *localtime_with_gmtoff_zone(const time_t *t, struct tm *result, long *gmtoff, const char **zone); /* - * The idea is come from Perl: + * The idea is borrowed from Perl: * http://use.perl.org/articles/08/02/07/197204.shtml * - * compat_common_month_table is generated by following program. - * This table finds the last month which start the same day of a week. - * The year 2037 is not used because + * compat_common_month_table is generated by the following program. + * This table finds the last month which starts at the same day of a week. + * The year 2037 is not used because: * http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=522949 * * #!/usr/bin/ruby @@ -1502,8 +1502,8 @@ VALUE timev; int y, wday; - /* The first DST is at 1916 in German. - * So we don't need to care DST before that. */ + /* Daylight Saving Time was introduced in 1916. + * So we don't need to care about DST before that. */ if (lt(vtm_utc->year, INT2FIX(1916))) { VALUE off = INT2FIX(0); int isdst = 0; @@ -1537,7 +1537,7 @@ return off; } - /* It is difficult to guess future. */ + /* It is difficult to guess the future. */ vtm2 = *vtm_utc; @@ -1943,7 +1943,7 @@ /* * Document-method: now * - * Synonym for <code>Time.new</code>. Returns a +Time+ object + * Alias for Time::new. Returns a Time object * initialized to the current system time. */ @@ -2220,20 +2220,21 @@ * Time.new -> time * Time.new(year, month=nil, day=nil, hour=nil, min=nil, sec=nil, utc_offset=nil) -> time * - * Returns a <code>Time</code> object. + * Returns a Time object. * - * It is initialized to the current system time if no argument. - * <b>Note:</b> The object created will be created using the - * resolution available on your system clock, and so may include - * fractional seconds. + * It is initialized to the current system time if no argument is given. * - * If one or more arguments specified, the time is initialized - * to the specified time. - * _sec_ may have fraction if it is a rational. + * *Note:* The new object will use the resolution available on your + * system clock, and may include fractional seconds. * - * _utc_offset_ is the offset from UTC. - * It is a string such as "+09:00" or a number of seconds such as 32400. + * If one or more arguments specified, the time is initialized to the specified + * time. * + * +sec+ may have fraction if it is a rational. + * + * +utc_offset+ is the offset from UTC. + * It can be a string such as "+09:00" or a number of seconds such as 32400. + * * a = Time.new #=> 2007-11-19 07:50:02 -0600 * b = Time.new #=> 2007-11-19 07:50:02 -0600 * a == b #=> false @@ -2488,7 +2489,7 @@ * call-seq: * Time.now -> time * - * Creates a new time object for the current time. + * Creates a new Time object for the current time. * * Time.now #=> 2009-06-24 12:39:54 +0900 */ @@ -2505,21 +2506,21 @@ * Time.at(seconds_with_frac) -> time * Time.at(seconds, microseconds_with_frac) -> time * - * Creates a new time object with the value given by <i>time</i>, - * the given number of <i>seconds_with_frac</i>, or - * <i>seconds</i> and <i>microseconds_with_frac</i> from the Epoch. - * <i>seconds_with_frac</i> and <i>microseconds_with_frac</i> - * can be Integer, Float, Rational, or other Numeric. + * Creates a new Time object with the value given by +time+, + * the given number of +seconds_with_frac+, or + * +seconds+ and +microseconds_with_frac+ since the Epoch. + * +seconds_with_frac+ and +microseconds_with_frac+ + * can be an Integer, Float, Rational, or other Numeric. * non-portable feature allows the offset to be negative on some systems. * * If a numeric argument is given, the result is in local time. * - * Time.at(0) #=> 1969-12-31 18:00:00 -0600 - * Time.at(Time.at(0)) #=> 1969-12-31 18:00:00 -0600 - * Time.at(946702800) #=> 1999-12-31 23:00:00 -0600 - * 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(0) #=> 1969-12-31 18:00:00 -0600 + * Time.at(Time.at(0)) #=> 1969-12-31 18:00:00 -0600 + * Time.at(946702800) #=> 1999-12-31 23:00:00 -0600 + * Time.at(-284061600) #=> 1960-12-31 00:00:00 -0600 + * Time.at(946684800.2).usec #=> 200000 + * Time.at(946684800, 123456.789).nsec #=> 123456789 */ static VALUE @@ -3118,16 +3119,16 @@ * Time.gm(year, month, day, hour, min, sec, usec_with_frac) -> time * Time.gm(sec, min, hour, day, month, year, wday, yday, isdst, tz) -> time * - * Creates a time based on given values, interpreted as UTC (GMT). The + * Creates a Time object based on given values, interpreted as UTC (GMT). The * year must be specified. Other values default to the minimum value - * for that field (and may be <code>nil</code> or omitted). Months may + * for that field (and may be +nil+ or omitted). Months may * be specified by numbers from 1 to 12, or by the three-letter English * month names. Hours are specified on a 24-hour clock (0..23). Raises - * an <code>ArgumentError</code> if any values are out of range. Will - * also accept ten arguments in the order output by - * <code>Time#to_a</code>. - * <i>sec_with_frac</i> and <i>usec_with_frac</i> can have a fractional part. + * an ArgumentError if any values are out of range. Will + * also accept ten arguments in the order output by Time#to_a. * + * +sec_with_frac+ and +usec_with_frac+ can have a fractional part. + * * Time.utc(2000,"jan",1,20,15,1) #=> 2000-01-01 20:15:01 UTC * Time.gm(2000,"jan",1,20,15,1) #=> 2000-01-01 20:15:01 UTC */ @@ -3156,7 +3157,7 @@ * Time.mktime(year, month, day, hour, min, sec, usec_with_frac) -> time * Time.mktime(sec, min, hour, day, month, year, wday, yday, isdst, tz) -> time * - * Same as <code>Time::gm</code>, but interprets the values in the + * Same as Time::gm, but interprets the values in the * local time zone. * * Time.local(2000,"jan",1,20,15,1) #=> 2000-01-01 20:15:01 -0600 @@ -3173,7 +3174,7 @@ * time.to_i -> int * time.tv_sec -> int * - * Returns the value of <i>time</i> as an integer number of seconds + * Returns the value of _time_ as an integer number of seconds * since the Epoch. * * t = Time.now @@ -3194,7 +3195,7 @@ * call-seq: * time.to_f -> float * - * Returns the value of <i>time</i> as a floating point number of + * Returns the value of _time_ as a floating point number of * seconds since the Epoch. * * t = Time.now @@ -3202,7 +3203,7 @@ * t.to_i #=> 1270968744 * * Note that IEEE 754 double is not accurate enough to represent - * number of nanoseconds from the Epoch. + * the number of nanoseconds since the Epoch. */ static VALUE @@ -3218,15 +3219,15 @@ * call-seq: * time.to_r -> a_rational * - * Returns the value of <i>time</i> as a rational number of seconds + * Returns the value of _time_ as a rational number of seconds * since the Epoch. * * t = Time.now * p t.to_r #=> (1270968792716287611/1000000000) * * This methods is intended to be used to get an accurate value - * representing nanoseconds from the Epoch. You can use this - * to convert time to another Epoch. + * representing the nanoseconds since the Epoch. You can use this method + * to convert _time_ to another Epoch. */ static VALUE @@ -3248,7 +3249,7 @@ * time.usec -> int * time.tv_usec -> int * - * Returns just the number of microseconds for <i>time</i>. + * Returns the number of microseconds for _time_. * * t = Time.now #=> 2007-11-19 08:03:26 -0600 * "%10.6f" % t.to_f #=> "1195481006.775195" @@ -3273,16 +3274,17 @@ * time.nsec -> int * time.tv_nsec -> int * - * Returns just the number of nanoseconds for <i>time</i>. + * Returns the number of nanoseconds for _time_. * * t = Time.now #=> 2007-11-17 15:18:03 +0900 * "%10.9f" % t.to_f #=> "1195280283.536151409" * t.nsec #=> 536151406 * - * The lowest digit of to_f and nsec is different because + * The lowest digits of #to_f and #nsec are different because * IEEE 754 double is not accurate enough to represent - * nanoseconds from the Epoch. - * The accurate value is returned by nsec. + * the exact number of nanoseconds since the Epoch. + * + * The more accurate value is returned by #nsec. */ static VALUE @@ -3298,18 +3300,19 @@ * call-seq: * time.subsec -> number * - * Returns just the fraction for <i>time</i>. + * Returns the fraction for _time_. * - * The result is possibly rational. + * The return value can be a rational number. * * t = Time.now #=> 2009-03-26 22:33:12 +0900 * "%10.9f" % t.to_f #=> "1238074392.940563917" * t.subsec #=> (94056401/100000000) * - * The lowest digit of to_f and subsec is different because + * The lowest digits of #to_f and #subsec are different because * IEEE 754 double is not accurate enough to represent - * the rational. - * The accurate value is returned by subsec. + * the rational number. + * + * The more accurate value is returned by #subsec. */ static VALUE @@ -3325,7 +3328,10 @@ * call-seq: * time <=> other_time -> -1, 0, +1 or nil * - * Comparison---Compares <i>time</i> with <i>other_time</i>. + * Comparison---Compares _time_ with +other_time+. + * The return value is ++1+ if _time_ is greater than + * +other_time+, +0+ if _time_ is equal to +other_time+ and + * +-1+ if _time_ is smaller than +other_time+. * * t = Time.now #=> 2007-11-19 08:12:12 -0600 * t2 = t + 2592000 #=> 2007-12-19 08:12:12 -0600 @@ -3369,9 +3375,8 @@ * call-seq: * time.eql?(other_time) * - * Return <code>true</code> if <i>time</i> and <i>other_time</i> are - * both <code>Time</code> objects with the same seconds and fractional - * seconds. + * Returns +true+ if _time_ and +other_time+ are + * both Time objects with the same seconds and fractional seconds. */ static VALUE @@ -3392,8 +3397,7 @@ * time.utc? -> true or false * time.gmt? -> true or false * - * Returns <code>true</code> if <i>time</i> represents a time in UTC - * (GMT). + * Returns +true+ if _time_ represents a time in UTC (GMT). * * t = Time.now #=> 2007-11-19 08:15:23 -0600 * t.utc? #=> false @@ -3420,7 +3424,7 @@ * call-seq: * time.hash -> fixnum * - * Return a hash code for this time object. + * Returns a hash code for this Time object. */ static VALUE @@ -3483,10 +3487,10 @@ * time.localtime -> time * time.localtime(utc_offset) -> time * - * Converts <i>time</i> to local time (using the local time zone in + * Converts _time_ to local time (using the local time zone in * effect for this process) modifying the receiver. * - * If _utc_offset_ is given, it is used instead of the local time. + * If +utc_offset+ is given, it is used instead of the local time. * * t = Time.utc(2000, "jan", 1, 20, 15, 1) #=> 2000-01-01 20:15:01 UTC * t.utc? #=> true @@ -3520,7 +3524,7 @@ * time.gmtime -> time * time.utc -> time * - * Converts <i>time</i> to UTC (GMT), modifying the receiver. + * Converts _time_ to UTC (GMT), modifying the receiver. * * t = Time.now #=> 2007-11-19 08:18:31 -0600 * t.gmt? #=> false @@ -3594,10 +3598,10 @@ * time.getlocal -> new_time * time.getlocal(utc_offset) -> new_time * - * Returns a new <code>new_time</code> object representing <i>time</i> in + * Returns a new Time object representing _time_ in * local time (using the local time zone in effect for this process). * - * If _utc_offset_ is given, it is used instead of the local time. + * If +utc_offset+ is given, it is used instead of the local time. * * t = Time.utc(2000,1,1,20,15,1) #=> 2000-01-01 20:15:01 UTC * t.utc? #=> true @@ -3634,8 +3638,7 @@ * time.getgm -> new_time * time.getutc -> new_time * - * Returns a new <code>new_time</code> object representing <i>time</i> in - * UTC. + * Returns a new Time object representing _time_ in UTC. * * t = Time.local(2000,1,1,20,15,1) #=> 2000-01-01 20:15:01 -0600 * t.gmt? #=> false @@ -3665,7 +3668,7 @@ * time.asctime -> string * time.ctime -> string * - * Returns a canonical string representation of <i>time</i>. + * Returns a canonical string representation of _time_. * * Time.now.asctime #=> "Wed Apr 9 08:56:03 2003" */ @@ -3681,15 +3684,15 @@ * time.inspect -> string * time.to_s -> string * - * Returns a string representing <i>time</i>. Equivalent to calling - * <code>Time#strftime</code> with a format string of - * ``<code>%Y-%m-%d</code> <code>%H:%M:%S</code> <code>%z</code>'' - * for a local time and - * ``<code>%Y-%m-%d</code> <code>%H:%M:%S</code> <code>UTC</code>'' - * for a UTC time. + * Returns a string representing _time_. Equivalent to calling + * #strftime with the appropriate format string. * - * Time.now.to_s #=> "2007-10-05 16:09:51 +0900" - * Time.now.utc.to_s #=> "2007-10-05 07:09:51 UTC" + * 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.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 @@ -3729,8 +3732,8 @@ * call-seq: * time + numeric -> time * - * Addition---Adds some number of seconds (possibly fractional) to - * <i>time</i> and returns that value as a new time. + * Addition --- Adds some number of seconds (possibly fractional) to + * _time_ and returns that value as a new Time object. * * t = Time.now #=> 2007-11-19 08:22:21 -0600 * t + (60 * 60 * 24) #=> 2007-11-20 08:22:21 -0600 @@ -3753,9 +3756,9 @@ * time - other_time -> float * time - numeric -> time * - * Difference---Returns a new time that represents the difference - * between two times, or subtracts the given number of seconds in - * <i>numeric</i> from <i>time</i>. + * Difference --- Returns a new Time object that represents the difference + * between _time_ and +other_time+, or subtracts the given number + * of seconds in +numeric+ from _time_. * * t = Time.now #=> 2007-11-19 08:23:10 -0600 * t2 = t + 2592000 #=> 2007-12-19 08:23:10 -0600 @@ -3782,11 +3785,15 @@ * call-seq: * time.succ -> new_time * - * Return a new time object, one second later than <code>time</code>. + * Returns a new Time object, one second later than _time_. * Time#succ is obsolete since 1.9.2 for time is not a discrete value. * * t = Time.now #=> 2007-11-19 08:23:57 -0600 * t.succ #=> 2007-11-19 08:23:58 -0600 + * + * Use instead <code>time + 1</code> + * + * t + 1 #=> 2007-11-19 08:23:58 -0600 */ VALUE @@ -3810,8 +3817,8 @@ * time.round([ndigits]) -> new_time * * 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. + * It returns a new Time object. + * +ndigits+ should be zero or positive integer. * * require 'time' * @@ -3883,11 +3890,11 @@ * call-seq: * time.sec -> fixnum * - * Returns the second of the minute (0..60) for <i>time</i>. + * Returns the second of the minute (0..60) for _time_. * - * <em>[Yes, seconds range from zero to 60. This allows the system to inject - * leap seconds. See http://en.wikipedia.org/wiki/Leap_second for further - * details.]</em> + * *Note:* Seconds range from zero to 60 to allow the system to inject + * leap seconds. See http://en.wikipedia.org/wiki/Leap_second for further + * details. * * t = Time.now #=> 2007-11-19 08:25:02 -0600 * t.sec #=> 2 @@ -3907,7 +3914,7 @@ * call-seq: * time.min -> fixnum * - * Returns the minute of the hour (0..59) for <i>time</i>. + * Returns the minute of the hour (0..59) for _time_. * * t = Time.now #=> 2007-11-19 08:25:51 -0600 * t.min #=> 25 @@ -3927,7 +3934,7 @@ * call-seq: * time.hour -> fixnum * - * Returns the hour of the day (0..23) for <i>time</i>. + * Returns the hour of the day (0..23) for _time_. * * t = Time.now #=> 2007-11-19 08:26:20 -0600 * t.hour #=> 8 @@ -3948,7 +3955,7 @@ * time.day -> fixnum * time.mday -> fixnum * - * Returns the day of the month (1..n) for <i>time</i>. + * Returns the day of the month (1..n) for _time_. * * t = Time.now #=> 2007-11-19 08:27:03 -0600 * t.day #=> 19 @@ -3970,7 +3977,7 @@ * time.mon -> fixnum * time.month -> fixnum * - * Returns the month of the year (1..12) for <i>time</i>. + * Returns the month of the year (1..12) for _time_. * * t = Time.now #=> 2007-11-19 08:27:30 -0600 * t.mon #=> 11 @@ -3991,7 +3998,7 @@ * call-seq: * time.year -> fixnum * - * Returns the year for <i>time</i> (including the century). + * Returns the year for _time_ (including the century). * * t = Time.now #=> 2007-11-19 08:27:51 -0600 * t.year #=> 2007 @@ -4046,7 +4053,7 @@ * call-seq: * time.sunday? -> true or false * - * Returns <code>true</code> if <i>time</i> represents Sunday. + * Returns +true+ if _time_ represents Sunday. * * t = Time.local(1990, 4, 1) #=> 1990-04-01 00:00:00 -0600 * t.sunday? #=> true @@ -4062,7 +4069,7 @@ * call-seq: * time.monday? -> true or false * - * Returns <code>true</code> if <i>time</i> represents Monday. + * Returns +true+ if _time_ represents Monday. * * t = Time.local(2003, 8, 4) #=> 2003-08-04 00:00:00 -0500 * p t.monday? #=> true @@ -4078,7 +4085,7 @@ * call-seq: * time.tuesday? -> true or false * - * Returns <code>true</code> if <i>time</i> represents Tuesday. + * Returns +true+ if _time_ represents Tuesday. * * t = Time.local(1991, 2, 19) #=> 1991-02-19 00:00:00 -0600 * p t.tuesday? #=> true @@ -4094,7 +4101,7 @@ * call-seq: * time.wednesday? -> true or false * - * Returns <code>true</code> if <i>time</i> represents Wednesday. + * Returns +true+ if _time_ represents Wednesday. * * t = Time.local(1993, 2, 24) #=> 1993-02-24 00:00:00 -0600 * p t.wednesday? #=> true @@ -4110,7 +4117,7 @@ * call-seq: * time.thursday? -> true or false * - * Returns <code>true</code> if <i>time</i> represents Thursday. + * Returns +true+ if _time_ represents Thursday. * * t = Time.local(1995, 12, 21) #=> 1995-12-21 00:00:00 -0600 * p t.thursday? #=> true @@ -4126,7 +4133,7 @@ * call-seq: * time.friday? -> true or false * - * Returns <code>true</code> if <i>time</i> represents Friday. + * Returns +true+ if _time_ represents Friday. * * t = Time.local(1987, 12, 18) #=> 1987-12-18 00:00:00 -0600 * t.f (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/