diff --git a/time.c b/time.c
index fbae712..33a7d88 100644
--- a/time.c
+++ b/time.c
@@ -1399,12 +1399,12 @@ gmtimew(wideval_t timew, struct vtm *result)
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 taken 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 @@ guess_local_offset(struct vtm *vtm_utc, int *isdst_ret, const char **zone_ret)
VALUE timev;
int y, wday;
- /* The first DST is at 1916 in German.
- * So we don't need to care DST before that. */
+ /* The first DST was in Germany 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 @@ guess_local_offset(struct vtm *vtm_utc, int *isdst_ret, const char **zone_ret)
return off;
}
- /* It is difficult to guess future. */
+ /* It is difficult to guess the future. */
vtm2 = *vtm_utc;
@@ -1943,7 +1943,7 @@ timew2timespec_exact(wideval_t timew, struct timespec *ts)
/*
* Document-method: now
*
- * Synonym for Time.new. Returns a +Time+ object
+ * Alias for +Time.new+. Returns a +Time+ object
* initialized to the current system time.
*/
@@ -2220,19 +2220,19 @@ time_init_1(int argc, VALUE *argv, VALUE time)
* Time.new -> time
* Time.new(year, month=nil, day=nil, hour=nil, min=nil, sec=nil, utc_offset=nil) -> time
*
- * Returns a Time object.
+ * Returns a +Time+ object.
*
- * It is initialized to the current system time if no argument.
- * Note: 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.
+ *
+ * *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.
* _sec_ may have fraction if it is a rational.
*
* _utc_offset_ is the offset from UTC.
- * It is a string such as "+09:00" or a number of seconds such as 32400.
+ * 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
@@ -2505,11 +2505,11 @@ time_s_now(VALUE klass)
* Time.at(seconds_with_frac) -> time
* Time.at(seconds, microseconds_with_frac) -> time
*
- * Creates a new time object with the value given by time,
- * the given number of seconds_with_frac, or
- * seconds and microseconds_with_frac from the Epoch.
- * seconds_with_frac and microseconds_with_frac
- * 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_ from the Epoch.
+ * _seconds_with_frac_ and _microseconds_with_frac_
+ * can be 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.
@@ -3118,15 +3118,15 @@ time_utc_or_local(int argc, VALUE *argv, int utc_p, VALUE klass)
* 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 nil 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 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.
+ * 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
@@ -3173,7 +3173,7 @@ time_s_mktime(int argc, VALUE *argv, VALUE klass)
* time.to_i -> int
* time.tv_sec -> int
*
- * Returns the value of time 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 +3194,7 @@ time_to_i(VALUE time)
* call-seq:
* time.to_f -> float
*
- * Returns the value of time 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 +3202,7 @@ time_to_i(VALUE time)
* 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 +3218,15 @@ time_to_f(VALUE time)
* call-seq:
* time.to_r -> a_rational
*
- * Returns the value of time 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 +3248,7 @@ time_to_r(VALUE time)
* time.usec -> int
* time.tv_usec -> int
*
- * Returns just the number of microseconds for time.
+ * 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 +3273,17 @@ time_usec(VALUE time)
* time.nsec -> int
* time.tv_nsec -> int
*
- * Returns just the number of nanoseconds for time.
+ * 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 +3299,19 @@ time_nsec(VALUE time)
* call-seq:
* time.subsec -> number
*
- * Returns just the fraction for time.
+ * 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 +3327,10 @@ time_subsec(VALUE time)
* call-seq:
* time <=> other_time -> -1, 0, +1 or nil
*
- * Comparison---Compares time with other_time.
+ * 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 +3374,8 @@ time_cmp(VALUE time1, VALUE time2)
* call-seq:
* time.eql?(other_time)
*
- * Return true if time and other_time are
- * both Time 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 +3396,7 @@ time_eql(VALUE time1, VALUE time2)
* time.utc? -> true or false
* time.gmt? -> true or false
*
- * Returns true if time 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 +3423,7 @@ time_utc_p(VALUE time)
* call-seq:
* time.hash -> fixnum
*
- * Return a hash code for this time object.
+ * Returns a hash code for this +Time+ object.
*/
static VALUE
@@ -3483,7 +3486,7 @@ time_localtime(VALUE time)
* time.localtime -> time
* time.localtime(utc_offset) -> time
*
- * Converts time 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.
@@ -3520,7 +3523,7 @@ time_localtime_m(int argc, VALUE *argv, VALUE time)
* time.gmtime -> time
* time.utc -> time
*
- * Converts time 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,7 +3597,7 @@ time_fixoff(VALUE time)
* time.getlocal -> new_time
* time.getlocal(utc_offset) -> new_time
*
- * Returns a new new_time object representing time 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.
@@ -3634,8 +3637,7 @@ time_getlocaltime(int argc, VALUE *argv, VALUE time)
* time.getgm -> new_time
* time.getutc -> new_time
*
- * Returns a new new_time object representing time 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 +3667,7 @@ static VALUE strftimev(const char *fmt, VALUE time, rb_encoding *enc);
* time.asctime -> string
* time.ctime -> string
*
- * Returns a canonical string representation of time.
+ * Returns a canonical string representation of _time_.
*
* Time.now.asctime #=> "Wed Apr 9 08:56:03 2003"
*/
@@ -3681,15 +3683,15 @@ time_asctime(VALUE time)
* time.inspect -> string
* time.to_s -> string
*
- * Returns a string representing time. Equivalent to calling
- * Time#strftime with a format string of
- * ``%Y-%m-%d %H:%M:%S %z''
- * for a local time and
- * ``%Y-%m-%d %H:%M:%S UTC''
- * 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
@@ -3730,7 +3732,7 @@ time_add(struct time_object *tobj, VALUE offset, int sign)
* time + numeric -> time
*
* Addition---Adds some number of seconds (possibly fractional) to
- * time and returns that value as a new time.
+ * _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 +3755,9 @@ time_plus(VALUE time1, VALUE time2)
* 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
- * numeric from time.
+ * 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 +3784,15 @@ time_minus(VALUE time1, VALUE time2)
* call-seq:
* time.succ -> new_time
*
- * Return a new time object, one second later than time.
+ * 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 time + 1
+ *
+ * t + 1 #=> 2007-11-19 08:23:58 -0600
*/
VALUE
@@ -3810,7 +3816,7 @@ rb_time_succ(VALUE time)
* 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.
+ * It returns a new +Time+ object.
* _ndigits_ should be zero or positive integer.
*
* require 'time'
@@ -3883,11 +3889,11 @@ time_round(int argc, VALUE *argv, VALUE time)
* call-seq:
* time.sec -> fixnum
*
- * Returns the second of the minute (0..60) for time.
+ * Returns the second of the minute (0..60) for _time_.
*
- * [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.]
+ * *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 +3913,7 @@ time_sec(VALUE time)
* call-seq:
* time.min -> fixnum
*
- * Returns the minute of the hour (0..59) for time.
+ * 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 +3933,7 @@ time_min(VALUE time)
* call-seq:
* time.hour -> fixnum
*
- * Returns the hour of the day (0..23) for time.
+ * 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 +3954,7 @@ time_hour(VALUE time)
* time.day -> fixnum
* time.mday -> fixnum
*
- * Returns the day of the month (1..n) for time.
+ * 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 +3976,7 @@ time_mday(VALUE time)
* time.mon -> fixnum
* time.month -> fixnum
*
- * Returns the month of the year (1..12) for time.
+ * 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 +3997,7 @@ time_mon(VALUE time)
* call-seq:
* time.year -> fixnum
*
- * Returns the year for time (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 +4052,7 @@ time_wday(VALUE time)
* call-seq:
* time.sunday? -> true or false
*
- * Returns true if time 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 +4068,7 @@ time_sunday(VALUE time)
* call-seq:
* time.monday? -> true or false
*
- * Returns true if time 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 +4084,7 @@ time_monday(VALUE time)
* call-seq:
* time.tuesday? -> true or false
*
- * Returns true if time 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 +4100,7 @@ time_tuesday(VALUE time)
* call-seq:
* time.wednesday? -> true or false
*
- * Returns true if time 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 +4116,7 @@ time_wednesday(VALUE time)
* call-seq:
* time.thursday? -> true or false
*
- * Returns true if time 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 +4132,7 @@ time_thursday(VALUE time)
* call-seq:
* time.friday? -> true or false
*
- * Returns true if time represents Friday.
+ * Returns +true+ if _time_ represents Friday.
*
* t = Time.local(1987, 12, 18) #=> 1987-12-18 00:00:00 -0600
* t.friday? #=> true
@@ -4142,7 +4148,7 @@ time_friday(VALUE time)
* call-seq:
* time.saturday? -> true or false
*
- * Returns true if time represents Saturday.
+ * Returns +true+ if _time_ represents Saturday.
*
* t = Time.local(2006, 6, 10) #=> 2006-06-10 00:00:00 -0500
* t.saturday? #=> true
@@ -4179,7 +4185,7 @@ time_yday(VALUE time)
* time.isdst -> true or false
* time.dst? -> true or false
*
- * Returns true if time occurs during Daylight
+ * Returns +true+ if _time_ occurs during Daylight
* Saving Time in its time zone.
*
* # CST6CDT:
@@ -4213,7 +4219,7 @@ time_isdst(VALUE time)
* call-seq:
* time.zone -> string
*
- * Returns the name of the time zone used for time. As of Ruby
+ * Returns the name of the time zone used for _time_. As of Ruby
* 1.8, returns ``UTC'' rather than ``GMT'' for UTC times.
*
* t = Time.gm(2000, "jan", 1, 20, 15, 1)
@@ -4244,7 +4250,7 @@ time_zone(VALUE time)
* time.gmtoff -> fixnum
* time.utc_offset -> fixnum
*
- * Returns the offset in seconds between the timezone of time
+ * Returns the offset in seconds between the timezone of _time_
* and UTC.
*
* t = Time.gm(2000,1,1,20,15,1) #=> 2000-01-01 20:15:01 UTC
@@ -4273,12 +4279,14 @@ time_utc_offset(VALUE time)
* call-seq:
* time.to_a -> array
*
- * Returns a ten-element array of values for time:
- * {[ sec, min, hour, day, month, year, wday, yday, isdst, zone
- * ]}. See the individual methods for an explanation of the
+ * Returns a ten-element _array_ of values for _time_:
+ *
+ * [sec, min, hour, day, month, year, wday, yday, isdst, zone]
+ *
+ * See the individual methods for an explanation of the
* valid ranges of each value. The ten elements can be passed directly
* to Time::utc or Time::local to create a
- * new Time.
+ * new +Time+ object.
*
* t = Time.now #=> 2007-11-19 08:36:01 -0600
* now = t.to_a #=> [1, 36, 8, 19, 11, 2007, 1, 323, false, "CST"]
@@ -4372,30 +4380,30 @@ strftimev(const char *fmt, VALUE time, rb_encoding *enc)
* call-seq:
* time.strftime( string ) -> string
*
- * Formats time according to the directives in the given format
- * string.
- * The directives begins with a percent (%) character.
+ * Formats _time_ according to the directives in the given format string.
+ *
+ * The directives begin with a percent (%) character.
* Any text not listed as a directive will be passed through to the
* output string.
*
* The directive consists of a percent (%) character,
* zero or more flags, optional minimum field width,
* optional modifier and a conversion specifier
- * as follows.
+ * as follows:
*
* %
*
* Flags:
- * - don't pad a numerical output.
- * _ use spaces for padding.
- * 0 use zeros for padding.
- * ^ upcase the result string.
- * # change case.
- * : use colons for %z.
+ * - don't pad a numerical output
+ * _ use spaces for padding
+ * 0 use zeros for padding
+ * ^ upcase the result string
+ * # change case
+ * : use colons for %z
*
* The minimum field width specifies the minimum width.
*
- * The modifier is "E" and "O".
+ * The modifiers are "E" and "O".
* They are ignored.
*
* Format directives:
@@ -4403,7 +4411,7 @@ strftimev(const char *fmt, VALUE time, rb_encoding *enc)
* Date (Year, Month, Day):
* %Y - Year with century (can be negative, 4 digits at least)
* -0001, 0000, 1995, 2009, 14292, etc.
- * %C - year / 100 (round down. 20 in 2009)
+ * %C - year / 100 (rounded down such as 20 in 2009)
* %y - year % 100 (00..99)
*
* %m - Month of the year, zero-padded (01..12)
@@ -4448,7 +4456,7 @@ strftimev(const char *fmt, VALUE time, rb_encoding *enc)
* %z - Time zone as hour and minute offset from UTC (e.g. +0900)
* %:z - hour and minute offset from UTC with a colon (e.g. +09:00)
* %::z - hour, minute and second offset from UTC (e.g. +09:00:00)
- * %Z - Time zone abbreviation name or something similar information.
+ * %Z - Abbreviated time zone name or similar information.
*
* Weekday:
* %A - The full weekday name (``Sunday'')
@@ -4459,7 +4467,7 @@ strftimev(const char *fmt, VALUE time, rb_encoding *enc)
* %w - Day of the week (Sunday is 0, 0..6)
*
* ISO 8601 week-based year and week number:
- * The week 1 of YYYY starts with a Monday and includes YYYY-01-04.
+ * The first week of YYYY starts with a Monday and includes YYYY-01-04.
* The days in the year before the first week are in the last week of
* the previous year.
* %G - The week-based year
@@ -4467,10 +4475,10 @@ strftimev(const char *fmt, VALUE time, rb_encoding *enc)
* %V - Week number of the week-based year (01..53)
*
* Week number:
- * The week 1 of YYYY starts with a Sunday or Monday (according to %U
- * or %W). The days in the year before the first week are in week 0.
- * %U - Week number of the year. The week starts with Sunday. (00..53)
- * %W - Week number of the year. The week starts with Monday. (00..53)
+ * The first week of YYYY that starts with a Sunday or Monday (according to %U
+ * or %W). The days in the year before the first week are in week 0.
+ * %U - Week number of the year. The week starts with Sunday. (00..53)
+ * %W - Week number of the year. The week starts with Monday. (00..53)
*
* Seconds since the Epoch:
* %s - Number of seconds since 1970-01-01 00:00:00 UTC.
@@ -4492,21 +4500,18 @@ strftimev(const char *fmt, VALUE time, rb_encoding *enc)
* %T - 24-hour time (%H:%M:%S)
*
* This method is similar to 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 since Ruby 1.9.
- * (%Z is platform dependent, though.)
- * So, the result may differ even if a same format string is used in other
+ *
+ * While all directives are locale independant since Ruby 1.9 %Z is platform
+ * dependant.
+ * 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.
*
* %z is recommended over %Z.
* %Z doesn't identify the timezone.
* For example, "CST" is used at America/Chicago (-06:00),
* America/Havana (-05:00), Asia/Harbin (+08:00), Australia/Darwin (+09:30)
* and Australia/Adelaide (+10:30).
- * Also, %Z is highly dependent for OS.
+ * Also, %Z is highly dependent on the operating system.
* 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.
@@ -4862,9 +4867,9 @@ time_load(VALUE klass, VALUE str)
}
/*
- * Time is an abstraction of dates and times. Time is stored internally as
+ * +Time+ is an abstraction of dates and times. +Time+ is stored internally as
* the number of seconds with fraction since the _Epoch_, January 1, 1970
- * 00:00 UTC. Also see the library modules Date. The Time class treats GMT
+ * 00:00 UTC. Also see the library module +Date+. The +Time+ class treats GMT
* (Greenwich Mean Time) and UTC (Coordinated Universal Time) as equivalent.
* GMT is the older way of referring to these baseline times but persists in
* the names of calls on POSIX systems.
@@ -4873,23 +4878,24 @@ time_load(VALUE klass, VALUE str)
* with each other -- times that are apparently equal when displayed may be
* different when compared.
*
- * Since Ruby 1.9.2, Time implementation uses a signed 63 bit integer, Bignum or Rational.
+ * Since Ruby 1.9.2, +Time+ implementation uses a signed 63 bit integer,
+ * +Bignum+ or +Rational+.
* The integer is a number of nanoseconds since the _Epoch_ which can
* represent 1823-11-12 to 2116-02-20.
- * When Bignum or Rational is used (before 1823, after 2116, under nanosecond),
- * Time works slower than the integer is used.
+ * When +Bignum+ or +Rational+ is used (before 1823, after 2116, under
+ * nanosecond), +Time+ works slower as when integer is used.
*
* = Examples
*
* All of these examples were done using the EST timezone which is GMT-5.
*
- * == Creating a new Time instance
+ * == Creating a new +Time+ instance
*
- * You can create a new instance of time with Time.new. This will use the
- * current system time. Time.now is a synonym for this. You can also
- * pass parts of the time to Time.new such as year, month, minute, etc. When
+ * You can create a new instance of +Time+ with +Time.new+. This will use the
+ * current system time. +Time.now+ is an alias for this. You can also
+ * pass parts of the time to +Time.new+ such as year, month, minute, etc. When
* you want to construct a time this way you must pass at least a year. If you
- * pass the year with nothing else time with default to January 1 of that year
+ * pass the year with nothing else time will default to January 1 of that year
* at 00:00:00 with the current system timezone. Here are some examples:
*
* Time.new(2002) #=> 2002-01-01 00:00:00 -0500
@@ -4897,19 +4903,20 @@ time_load(VALUE klass, VALUE str)
* Time.new(2002, 10, 31) #=> 2002-10-31 00:00:00 -0500
* Time.new(2002, 10, 31, 2, 2, 2, "+02:00") #=> 2002-10-31 02:02:02 -0200
*
- * You can also use #gm, #local and #utc to infer GMT, local and UTC
- * timezones instead of using the current system setting.
+ * You can also use +#gm+, +#local+ and
+ * +#utc+ to infer GMT, local and UTC timezones instead of using
+ * the current system setting.
*
- * You can also create a new time using Time.at which takes the number of
+ * You can also create a new time using +Time.at+ which takes the number of
* seconds (or fraction of seconds) since the {Unix
* Epoch}[http://en.wikipedia.org/wiki/Unix_time].
*
* Time.at(628232400) #=> 1989-11-28 00:00:00 -0500
*
- * == Working with an instance of Time
+ * == Working with an instance of +Time+
*
- * Once you have an instance of time there is a multitude of things you can do
- * with it. Below are some examples. For all of the following examples, we
+ * Once you have an instance of +Time+ there is a multitude of things you can
+ * do with it. Below are some examples. For all of the following examples, we
* will work on the assumption that you have done the following:
*
* t = Time.new(1993, 02, 24, 12, 0, 0, "+09:00")
@@ -4930,7 +4937,7 @@ time_load(VALUE klass, VALUE str)
*
* t + (60*60*24*365) #=> 1994-02-24 12:00:00 +0900
*
- * How many second was that from the Unix Epoch?
+ * How many seconds was that from the Unix Epoch?
*
* t.to_i #=> 730522800
*