From 921e29ced5884f8b02dc9aa4851d77c30d743312 Mon Sep 17 00:00:00 2001 From: Bernd Homuth Date: Sat, 24 Nov 2012 10:51:40 +0100 Subject: [PATCH] reformat docs in time.c --- time.c | 168 ++++++++++++++++++++++++++++++++--------------------------------- 1 file changed, 84 insertions(+), 84 deletions(-) diff --git a/time.c b/time.c index 426db16..97d37ed 100644 --- a/time.c +++ b/time.c @@ -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,7 +2220,7 @@ 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 @@ -2505,21 +2505,21 @@ 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+ since 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. * - * 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 @@ -3120,13 +3120,13 @@ time_utc_or_local(int argc, VALUE *argv, int utc_p, VALUE klass) * * Creates a time 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 @@ -3156,7 +3156,7 @@ time_s_mkutc(int argc, VALUE *argv, VALUE klass) * 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 Time::gm, 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 +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 @@ -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,13 +3273,13 @@ 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. @@ -3298,7 +3298,7 @@ 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. * @@ -3306,7 +3306,7 @@ time_nsec(VALUE time) * "%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. @@ -3369,9 +3369,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 +3391,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 +3418,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 +3481,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 +3518,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 +3592,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 +3632,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 +3662,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" */ @@ -3730,7 +3727,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 @@ -3782,7 +3779,7 @@ 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 @@ -3810,7 +3807,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,7 +3880,7 @@ 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 @@ -3907,7 +3904,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 +3924,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 +3945,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 +3967,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 +3988,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 +4043,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 +4059,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 +4075,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 +4091,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 +4107,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 +4123,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 +4139,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 +4176,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 +4210,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 +4241,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 +4270,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. + * to Time::utc or Time::local to create a + * 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 +4371,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: @@ -4849,7 +4848,7 @@ end_submicro: ; * call-seq: * Time._load(string) -> time * - * Unmarshal a dumped +Time+ object. + * Unmarshal a dumped Time object. */ static VALUE @@ -4873,7 +4872,8 @@ 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), @@ -4885,9 +4885,9 @@ time_load(VALUE klass, VALUE str) * * == 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 * at 00:00:00 with the current system timezone. Here are some examples: @@ -4900,7 +4900,7 @@ time_load(VALUE klass, VALUE str) * 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]. * @@ -4908,8 +4908,8 @@ time_load(VALUE klass, VALUE str) * * == 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") -- 1.7.11.1