From 98a8afe3f80d82ffddacd7eaf4bbc16c72d9f2be Mon Sep 17 00:00:00 2001 From: Bernd Homuth Date: Sat, 24 Nov 2012 10:58:26 +0100 Subject: [PATCH] changes to time.c docs --- time.c | 87 ++++++++++++++++++++++++++++++++++++------------------------------ 1 file changed, 47 insertions(+), 40 deletions(-) diff --git a/time.c b/time.c index 97d37ed..592965e 100644 --- a/time.c +++ b/time.c @@ -2222,10 +2222,10 @@ time_init_1(int argc, VALUE *argv, VALUE time) * * 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. @@ -3118,7 +3118,7 @@ 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 * be specified by numbers from 1 to 12, or by the three-letter English @@ -3281,8 +3281,9 @@ time_usec(VALUE time) * * 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 @@ -3300,7 +3301,7 @@ time_nsec(VALUE 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" @@ -3308,8 +3309,9 @@ time_nsec(VALUE time) * * 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 @@ -3678,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. + * + * 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" * - * Time.now.to_s #=> "2007-10-05 16:09:51 +0900" - * Time.now.utc.to_s #=> "2007-10-05 07:09:51 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 @@ -3750,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 @@ -3784,6 +3789,10 @@ time_minus(VALUE time1, VALUE time2) * * 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 @@ -3882,9 +3891,9 @@ time_round(int argc, VALUE *argv, VALUE 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 @@ -4402,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) @@ -4491,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. @@ -4863,7 +4869,7 @@ time_load(VALUE klass, VALUE str) /* * 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. @@ -4876,8 +4882,8 @@ time_load(VALUE klass, VALUE str) * 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 * @@ -4889,7 +4895,7 @@ time_load(VALUE klass, VALUE str) * 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,8 +4903,9 @@ 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 * seconds (or fraction of seconds) since the {Unix -- 1.7.11.1