Project

General

Profile

Bug #7326 ยป time_patch0004.diff

bt (Bernd Homuth), 11/25/2012 07:00 AM

View differences:

time.c
2227 2227
 *  *Note:* The new object will use the resolution available on your
2228 2228
 *  system clock, and may include fractional seconds.
2229 2229
 *
2230
 *  If one or more arguments specified, the time is initialized
2231
 *  to the specified time.
2232
 *  _sec_ may have fraction if it is a rational.
2230
 *  If one or more arguments specified, the time is initialized to the specified
2231
 *  time.
2233 2232
 *
2234
 *  _utc_offset_ is the offset from UTC.
2233
 *  +sec+ may have fraction if it is a rational.
2234
 *
2235
 *  +utc_offset+ is the offset from UTC.
2235 2236
 *  It can be a string such as "+09:00" or a number of seconds such as 32400.
2236 2237
 *
2237 2238
 *     a = Time.new      #=> 2007-11-19 07:50:02 -0600
......
2488 2489
 *  call-seq:
2489 2490
 *     Time.now -> time
2490 2491
 *
2491
 *  Creates a new time object for the current time.
2492
 *  Creates a new Time object for the current time.
2492 2493
 *
2493 2494
 *     Time.now            #=> 2009-06-24 12:39:54 +0900
2494 2495
 */
......
3489 3490
 *  Converts _time_ to local time (using the local time zone in
3490 3491
 *  effect for this process) modifying the receiver.
3491 3492
 *
3492
 *  If _utc_offset_ is given, it is used instead of the local time.
3493
 *  If +utc_offset+ is given, it is used instead of the local time.
3493 3494
 *
3494 3495
 *     t = Time.utc(2000, "jan", 1, 20, 15, 1) #=> 2000-01-01 20:15:01 UTC
3495 3496
 *     t.utc?                                  #=> true
......
3600 3601
 *  Returns a new Time object representing _time_ in
3601 3602
 *  local time (using the local time zone in effect for this process).
3602 3603
 *
3603
 *  If _utc_offset_ is given, it is used instead of the local time.
3604
 *  If +utc_offset+ is given, it is used instead of the local time.
3604 3605
 *
3605 3606
 *     t = Time.utc(2000,1,1,20,15,1)  #=> 2000-01-01 20:15:01 UTC
3606 3607
 *     t.utc?                          #=> true
......
3731 3732
 *  call-seq:
3732 3733
 *     time + numeric -> time
3733 3734
 *
3734
 *  Addition---Adds some number of seconds (possibly fractional) to
3735
 *  Addition --- Adds some number of seconds (possibly fractional) to
3735 3736
 *  _time_ and returns that value as a new Time object.
3736 3737
 *
3737 3738
 *     t = Time.now         #=> 2007-11-19 08:22:21 -0600
......
3755 3756
 *     time - other_time -> float
3756 3757
 *     time - numeric    -> time
3757 3758
 *
3758
 *  Difference---Returns a new Time object that represents the difference
3759
 *  Difference --- Returns a new Time object that represents the difference
3759 3760
 *  between _time_ and +other_time+, or subtracts the given number
3760 3761
 *  of seconds in +numeric+ from _time_.
3761 3762
 *
......
3817 3818
 *
3818 3819
 * Rounds sub seconds to a given precision in decimal digits (0 digits by default).
3819 3820
 * It returns a new Time object.
3820
 * _ndigits_ should be zero or positive integer.
3821
 * +ndigits+ should be zero or positive integer.
3821 3822
 *
3822 3823
 *     require 'time'
3823 3824
 *
time_patch0001.diff
1
From e96d86df690b5e4c6020d115d224b7b3b185e7cd Mon Sep 17 00:00:00 2001
2
From: Bernd Homuth <dev@hmt.im>
3
Date: Sat, 24 Nov 2012 10:32:49 +0100
4
Subject: [PATCH] language fixes in time.c
5

  
6
---
7
 time.c | 32 ++++++++++++++++----------------
8
 1 file changed, 16 insertions(+), 16 deletions(-)
9

  
10
diff --git a/time.c b/time.c
11
index fbae712..426db16 100644
12
--- a/time.c
13
+++ b/time.c
14
@@ -1399,12 +1399,12 @@ gmtimew(wideval_t timew, struct vtm *result)
15
 static struct tm *localtime_with_gmtoff_zone(const time_t *t, struct tm *result, long *gmtoff, const char **zone);
16
 
17
 /*
18
- * The idea is come from Perl:
19
+ * The idea is borrowed from Perl:
20
  * http://use.perl.org/articles/08/02/07/197204.shtml
21
  *
22
- * compat_common_month_table is generated by following program.
23
- * This table finds the last month which start the same day of a week.
24
- * The year 2037 is not used because
25
+ * compat_common_month_table is generated by the following program.
26
+ * This table finds the last month which starts at the same day of a week.
27
+ * The year 2037 is not used because:
28
  * http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=522949
29
  *
30
  *  #!/usr/bin/ruby
31
@@ -1502,8 +1502,8 @@ guess_local_offset(struct vtm *vtm_utc, int *isdst_ret, const char **zone_ret)
32
     VALUE timev;
33
     int y, wday;
34
 
35
-    /* The first DST is at 1916 in German.
36
-     * So we don't need to care DST before that. */
37
+    /* Daylight Saving Time was introduced in 1916.
38
+     * So we don't need to care about DST before that. */
39
     if (lt(vtm_utc->year, INT2FIX(1916))) {
40
         VALUE off = INT2FIX(0);
41
         int isdst = 0;
42
@@ -1537,7 +1537,7 @@ guess_local_offset(struct vtm *vtm_utc, int *isdst_ret, const char **zone_ret)
43
         return off;
44
     }
45
 
46
-    /* It is difficult to guess future. */
47
+    /* It is difficult to guess the future. */
48
 
49
     vtm2 = *vtm_utc;
50
 
51
@@ -2232,7 +2232,7 @@ time_init_1(int argc, VALUE *argv, VALUE time)
52
  *  _sec_ may have fraction if it is a rational.
53
  *
54
  *  _utc_offset_ is the offset from UTC.
55
- *  It is a string such as "+09:00" or a number of seconds such as 32400.
56
+ *  It can be a string such as "+09:00" or a number of seconds such as 32400.
57
  *
58
  *     a = Time.new      #=> 2007-11-19 07:50:02 -0600
59
  *     b = Time.new      #=> 2007-11-19 07:50:02 -0600
60
@@ -3202,7 +3202,7 @@ time_to_i(VALUE time)
61
  *     t.to_i              #=> 1270968744
62
  *
63
  *  Note that IEEE 754 double is not accurate enough to represent
64
- *  number of nanoseconds from the Epoch.
65
+ *  the number of nanoseconds since the Epoch.
66
  */
67
 
68
 static VALUE
69
@@ -4448,7 +4448,7 @@ strftimev(const char *fmt, VALUE time, rb_encoding *enc)
70
  *      %z - Time zone as hour and minute offset from UTC (e.g. +0900)
71
  *              %:z - hour and minute offset from UTC with a colon (e.g. +09:00)
72
  *              %::z - hour, minute and second offset from UTC (e.g. +09:00:00)
73
- *      %Z - Time zone abbreviation name or something similar information.
74
+ *      %Z - Abbreviated time zone name or similar information.
75
  *
76
  *    Weekday:
77
  *      %A - The full weekday name (``Sunday'')
78
@@ -4459,7 +4459,7 @@ strftimev(const char *fmt, VALUE time, rb_encoding *enc)
79
  *      %w - Day of the week (Sunday is 0, 0..6)
80
  *
81
  *    ISO 8601 week-based year and week number:
82
- *    The week 1 of YYYY starts with a Monday and includes YYYY-01-04.
83
+ *    The first week of YYYY starts with a Monday and includes YYYY-01-04.
84
  *    The days in the year before the first week are in the last week of
85
  *    the previous year.
86
  *      %G - The week-based year
87
@@ -4467,10 +4467,10 @@ strftimev(const char *fmt, VALUE time, rb_encoding *enc)
88
  *      %V - Week number of the week-based year (01..53)
89
  *
90
  *    Week number:
91
- *    The week 1 of YYYY starts with a Sunday or Monday (according to %U
92
- *    or %W).  The days in the year before the first week are in week 0.
93
- *      %U - Week number of the year.  The week starts with Sunday.  (00..53)
94
- *      %W - Week number of the year.  The week starts with Monday.  (00..53)
95
+ *    The first week of YYYY that starts with a Sunday or Monday (according to %U
96
+ *    or %W). The days in the year before the first week are in week 0.
97
+ *      %U - Week number of the year. The week starts with Sunday. (00..53)
98
+ *      %W - Week number of the year. The week starts with Monday. (00..53)
99
  *
100
  *    Seconds since the Epoch:
101
  *      %s - Number of seconds since 1970-01-01 00:00:00 UTC.
102
@@ -4930,7 +4930,7 @@ time_load(VALUE klass, VALUE str)
103
  *
104
  *    t + (60*60*24*365) #=> 1994-02-24 12:00:00 +0900
105
  *
106
- *  How many second was that from the Unix Epoch?
107
+ *  How many seconds was that since the Unix Epoch?
108
  *
109
  *    t.to_i #=> 730522800
110
  *
111
-- 
112
1.7.11.1
113

  
time_patch0002.diff
1
From 921e29ced5884f8b02dc9aa4851d77c30d743312 Mon Sep 17 00:00:00 2001
2
From: Bernd Homuth <dev@hmt.im>
3
Date: Sat, 24 Nov 2012 10:51:40 +0100
4
Subject: [PATCH] reformat docs in time.c
5

  
6
---
7
 time.c | 168 ++++++++++++++++++++++++++++++++---------------------------------
8
 1 file changed, 84 insertions(+), 84 deletions(-)
9

  
10
diff --git a/time.c b/time.c
11
index 426db16..97d37ed 100644
12
--- a/time.c
13
+++ b/time.c
14
@@ -1943,7 +1943,7 @@ timew2timespec_exact(wideval_t timew, struct timespec *ts)
15
 /*
16
  *  Document-method: now
17
  *
18
- *  Synonym for <code>Time.new</code>. Returns a +Time+ object
19
+ *  Alias for Time::new. Returns a Time object
20
  *  initialized to the current system time.
21
  */
22
 
23
@@ -2220,7 +2220,7 @@ time_init_1(int argc, VALUE *argv, VALUE time)
24
  *     Time.new -> time
25
  *     Time.new(year, month=nil, day=nil, hour=nil, min=nil, sec=nil, utc_offset=nil) -> time
26
  *
27
- *  Returns a <code>Time</code> object.
28
+ *  Returns a Time object.
29
  *
30
  *  It is initialized to the current system time if no argument.
31
  *  <b>Note:</b> The object created will be created using the
32
@@ -2505,21 +2505,21 @@ time_s_now(VALUE klass)
33
  *     Time.at(seconds_with_frac) -> time
34
  *     Time.at(seconds, microseconds_with_frac) -> time
35
  *
36
- *  Creates a new time object with the value given by <i>time</i>,
37
- *  the given number of <i>seconds_with_frac</i>, or
38
- *  <i>seconds</i> and <i>microseconds_with_frac</i> from the Epoch.
39
- *  <i>seconds_with_frac</i> and <i>microseconds_with_frac</i>
40
- *  can be Integer, Float, Rational, or other Numeric.
41
+ *  Creates a new Time object with the value given by +time+,
42
+ *  the given number of +seconds_with_frac+, or
43
+ *  +seconds+ and +microseconds_with_frac+ since the Epoch.
44
+ *  +seconds_with_frac+ and +microseconds_with_frac+
45
+ *  can be integer, Float, Rational, or other Numeric.
46
  *  non-portable feature allows the offset to be negative on some systems.
47
  *
48
  *  If a numeric argument is given, the result is in local time.
49
  *
50
- *     Time.at(0)            #=> 1969-12-31 18:00:00 -0600
51
- *     Time.at(Time.at(0))   #=> 1969-12-31 18:00:00 -0600
52
- *     Time.at(946702800)    #=> 1999-12-31 23:00:00 -0600
53
- *     Time.at(-284061600)   #=> 1960-12-31 00:00:00 -0600
54
- *     Time.at(946684800.2).usec #=> 200000
55
- *     Time.at(946684800, 123456.789).nsec #=> 123456789
56
+ *     Time.at(0)                           #=> 1969-12-31 18:00:00 -0600
57
+ *     Time.at(Time.at(0))                  #=> 1969-12-31 18:00:00 -0600
58
+ *     Time.at(946702800)                   #=> 1999-12-31 23:00:00 -0600
59
+ *     Time.at(-284061600)                  #=> 1960-12-31 00:00:00 -0600
60
+ *     Time.at(946684800.2).usec            #=> 200000
61
+ *     Time.at(946684800, 123456.789).nsec  #=> 123456789
62
  */
63
 
64
 static VALUE
65
@@ -3120,13 +3120,13 @@ time_utc_or_local(int argc, VALUE *argv, int utc_p, VALUE klass)
66
  *
67
  *  Creates a time based on given values, interpreted as UTC (GMT). The
68
  *  year must be specified. Other values default to the minimum value
69
- *  for that field (and may be <code>nil</code> or omitted). Months may
70
+ *  for that field (and may be +nil+ or omitted). Months may
71
  *  be specified by numbers from 1 to 12, or by the three-letter English
72
  *  month names. Hours are specified on a 24-hour clock (0..23). Raises
73
- *  an <code>ArgumentError</code> if any values are out of range. Will
74
- *  also accept ten arguments in the order output by
75
- *  <code>Time#to_a</code>.
76
- *  <i>sec_with_frac</i> and <i>usec_with_frac</i> can have a fractional part.
77
+ *  an ArgumentError if any values are out of range. Will
78
+ *  also accept ten arguments in the order output by Time#to_a.
79
+ *
80
+ *  +sec_with_frac+ and +usec_with_frac+ can have a fractional part.
81
  *
82
  *     Time.utc(2000,"jan",1,20,15,1)  #=> 2000-01-01 20:15:01 UTC
83
  *     Time.gm(2000,"jan",1,20,15,1)   #=> 2000-01-01 20:15:01 UTC
84
@@ -3156,7 +3156,7 @@ time_s_mkutc(int argc, VALUE *argv, VALUE klass)
85
  *   Time.mktime(year, month, day, hour, min, sec, usec_with_frac) -> time
86
  *   Time.mktime(sec, min, hour, day, month, year, wday, yday, isdst, tz) -> time
87
  *
88
- *  Same as <code>Time::gm</code>, but interprets the values in the
89
+ *  Same as Time::gm, but interprets the values in the
90
  *  local time zone.
91
  *
92
  *     Time.local(2000,"jan",1,20,15,1)   #=> 2000-01-01 20:15:01 -0600
93
@@ -3173,7 +3173,7 @@ time_s_mktime(int argc, VALUE *argv, VALUE klass)
94
  *     time.to_i   -> int
95
  *     time.tv_sec -> int
96
  *
97
- *  Returns the value of <i>time</i> as an integer number of seconds
98
+ *  Returns the value of _time_ as an integer number of seconds
99
  *  since the Epoch.
100
  *
101
  *     t = Time.now
102
@@ -3194,7 +3194,7 @@ time_to_i(VALUE time)
103
  *  call-seq:
104
  *     time.to_f -> float
105
  *
106
- *  Returns the value of <i>time</i> as a floating point number of
107
+ *  Returns the value of _time_ as a floating point number of
108
  *  seconds since the Epoch.
109
  *
110
  *     t = Time.now
111
@@ -3218,15 +3218,15 @@ time_to_f(VALUE time)
112
  *  call-seq:
113
  *     time.to_r -> a_rational
114
  *
115
- *  Returns the value of <i>time</i> as a rational number of seconds
116
+ *  Returns the value of _time_ as a rational number of seconds
117
  *  since the Epoch.
118
  *
119
  *     t = Time.now
120
  *     p t.to_r            #=> (1270968792716287611/1000000000)
121
  *
122
  *  This methods is intended to be used to get an accurate value
123
- *  representing nanoseconds from the Epoch.  You can use this
124
- *  to convert time to another Epoch.
125
+ *  representing the nanoseconds since the Epoch. You can use this method
126
+ *  to convert _time_ to another Epoch.
127
  */
128
 
129
 static VALUE
130
@@ -3248,7 +3248,7 @@ time_to_r(VALUE time)
131
  *     time.usec    -> int
132
  *     time.tv_usec -> int
133
  *
134
- *  Returns just the number of microseconds for <i>time</i>.
135
+ *  Returns the number of microseconds for _time_.
136
  *
137
  *     t = Time.now        #=> 2007-11-19 08:03:26 -0600
138
  *     "%10.6f" % t.to_f   #=> "1195481006.775195"
139
@@ -3273,13 +3273,13 @@ time_usec(VALUE time)
140
  *     time.nsec    -> int
141
  *     time.tv_nsec -> int
142
  *
143
- *  Returns just the number of nanoseconds for <i>time</i>.
144
+ *  Returns the number of nanoseconds for _time_.
145
  *
146
  *     t = Time.now        #=> 2007-11-17 15:18:03 +0900
147
  *     "%10.9f" % t.to_f   #=> "1195280283.536151409"
148
  *     t.nsec              #=> 536151406
149
  *
150
- *  The lowest digit of to_f and nsec is different because
151
+ *  The lowest digits of #to_f and #nsec are different because
152
  *  IEEE 754 double is not accurate enough to represent
153
  *  nanoseconds from the Epoch.
154
  *  The accurate value is returned by nsec.
155
@@ -3298,7 +3298,7 @@ time_nsec(VALUE time)
156
  *  call-seq:
157
  *     time.subsec    -> number
158
  *
159
- *  Returns just the fraction for <i>time</i>.
160
+ *  Returns the fraction for _time_.
161
  *
162
  *  The result is possibly rational.
163
  *
164
@@ -3306,7 +3306,7 @@ time_nsec(VALUE time)
165
  *     "%10.9f" % t.to_f   #=> "1238074392.940563917"
166
  *     t.subsec            #=> (94056401/100000000)
167
  *
168
- *  The lowest digit of to_f and subsec is different because
169
+ *  The lowest digits of #to_f and #subsec are different because
170
  *  IEEE 754 double is not accurate enough to represent
171
  *  the rational.
172
  *  The accurate value is returned by subsec.
173
@@ -3369,9 +3369,8 @@ time_cmp(VALUE time1, VALUE time2)
174
  * call-seq:
175
  *  time.eql?(other_time)
176
  *
177
- * Return <code>true</code> if <i>time</i> and <i>other_time</i> are
178
- * both <code>Time</code> objects with the same seconds and fractional
179
- * seconds.
180
+ * Returns +true+ if _time_ and +other_time+ are
181
+ * both Time objects with the same seconds and fractional seconds.
182
  */
183
 
184
 static VALUE
185
@@ -3392,8 +3391,7 @@ time_eql(VALUE time1, VALUE time2)
186
  *     time.utc? -> true or false
187
  *     time.gmt? -> true or false
188
  *
189
- *  Returns <code>true</code> if <i>time</i> represents a time in UTC
190
- *  (GMT).
191
+ *  Returns +true+ if _time_ represents a time in UTC (GMT).
192
  *
193
  *     t = Time.now                        #=> 2007-11-19 08:15:23 -0600
194
  *     t.utc?                              #=> false
195
@@ -3420,7 +3418,7 @@ time_utc_p(VALUE time)
196
  * call-seq:
197
  *   time.hash   -> fixnum
198
  *
199
- * Return a hash code for this time object.
200
+ * Returns a hash code for this Time object.
201
  */
202
 
203
 static VALUE
204
@@ -3483,7 +3481,7 @@ time_localtime(VALUE time)
205
  *     time.localtime -> time
206
  *     time.localtime(utc_offset) -> time
207
  *
208
- *  Converts <i>time</i> to local time (using the local time zone in
209
+ *  Converts _time_ to local time (using the local time zone in
210
  *  effect for this process) modifying the receiver.
211
  *
212
  *  If _utc_offset_ is given, it is used instead of the local time.
213
@@ -3520,7 +3518,7 @@ time_localtime_m(int argc, VALUE *argv, VALUE time)
214
  *     time.gmtime    -> time
215
  *     time.utc       -> time
216
  *
217
- *  Converts <i>time</i> to UTC (GMT), modifying the receiver.
218
+ *  Converts _time_ to UTC (GMT), modifying the receiver.
219
  *
220
  *     t = Time.now   #=> 2007-11-19 08:18:31 -0600
221
  *     t.gmt?         #=> false
222
@@ -3594,7 +3592,7 @@ time_fixoff(VALUE time)
223
  *     time.getlocal -> new_time
224
  *     time.getlocal(utc_offset) -> new_time
225
  *
226
- *  Returns a new <code>new_time</code> object representing <i>time</i> in
227
+ *  Returns a new Time object representing _time_ in
228
  *  local time (using the local time zone in effect for this process).
229
  *
230
  *  If _utc_offset_ is given, it is used instead of the local time.
231
@@ -3634,8 +3632,7 @@ time_getlocaltime(int argc, VALUE *argv, VALUE time)
232
  *     time.getgm  -> new_time
233
  *     time.getutc -> new_time
234
  *
235
- *  Returns a new <code>new_time</code> object representing <i>time</i> in
236
- *  UTC.
237
+ *  Returns a new Time object representing _time_ in UTC.
238
  *
239
  *     t = Time.local(2000,1,1,20,15,1)   #=> 2000-01-01 20:15:01 -0600
240
  *     t.gmt?                             #=> false
241
@@ -3665,7 +3662,7 @@ static VALUE strftimev(const char *fmt, VALUE time, rb_encoding *enc);
242
  *     time.asctime -> string
243
  *     time.ctime   -> string
244
  *
245
- *  Returns a canonical string representation of <i>time</i>.
246
+ *  Returns a canonical string representation of _time_.
247
  *
248
  *     Time.now.asctime   #=> "Wed Apr  9 08:56:03 2003"
249
  */
250
@@ -3730,7 +3727,7 @@ time_add(struct time_object *tobj, VALUE offset, int sign)
251
  *     time + numeric -> time
252
  *
253
  *  Addition---Adds some number of seconds (possibly fractional) to
254
- *  <i>time</i> and returns that value as a new time.
255
+ *  _time_ and returns that value as a new Time object.
256
  *
257
  *     t = Time.now         #=> 2007-11-19 08:22:21 -0600
258
  *     t + (60 * 60 * 24)   #=> 2007-11-20 08:22:21 -0600
259
@@ -3782,7 +3779,7 @@ time_minus(VALUE time1, VALUE time2)
260
  * call-seq:
261
  *   time.succ   -> new_time
262
  *
263
- * Return a new time object, one second later than <code>time</code>.
264
+ * Returns a new Time object, one second later than _time_.
265
  * Time#succ is obsolete since 1.9.2 for time is not a discrete value.
266
  *
267
  *     t = Time.now       #=> 2007-11-19 08:23:57 -0600
268
@@ -3810,7 +3807,7 @@ rb_time_succ(VALUE time)
269
  *   time.round([ndigits])   -> new_time
270
  *
271
  * Rounds sub seconds to a given precision in decimal digits (0 digits by default).
272
- * It returns a new time object.
273
+ * It returns a new Time object.
274
  * _ndigits_ should be zero or positive integer.
275
  *
276
  *     require 'time'
277
@@ -3883,7 +3880,7 @@ time_round(int argc, VALUE *argv, VALUE time)
278
  *  call-seq:
279
  *     time.sec -> fixnum
280
  *
281
- *  Returns the second of the minute (0..60) for <i>time</i>.
282
+ *  Returns the second of the minute (0..60) for _time_.
283
  *
284
  *  <em>[Yes, seconds range from zero to 60.  This allows the system to inject
285
  *  leap seconds.  See http://en.wikipedia.org/wiki/Leap_second for further
286
@@ -3907,7 +3904,7 @@ time_sec(VALUE time)
287
  *  call-seq:
288
  *     time.min -> fixnum
289
  *
290
- *  Returns the minute of the hour (0..59) for <i>time</i>.
291
+ *  Returns the minute of the hour (0..59) for _time_.
292
  *
293
  *     t = Time.now   #=> 2007-11-19 08:25:51 -0600
294
  *     t.min          #=> 25
295
@@ -3927,7 +3924,7 @@ time_min(VALUE time)
296
  *  call-seq:
297
  *     time.hour -> fixnum
298
  *
299
- *  Returns the hour of the day (0..23) for <i>time</i>.
300
+ *  Returns the hour of the day (0..23) for _time_.
301
  *
302
  *     t = Time.now   #=> 2007-11-19 08:26:20 -0600
303
  *     t.hour         #=> 8
304
@@ -3948,7 +3945,7 @@ time_hour(VALUE time)
305
  *     time.day  -> fixnum
306
  *     time.mday -> fixnum
307
  *
308
- *  Returns the day of the month (1..n) for <i>time</i>.
309
+ *  Returns the day of the month (1..n) for _time_.
310
  *
311
  *     t = Time.now   #=> 2007-11-19 08:27:03 -0600
312
  *     t.day          #=> 19
313
@@ -3970,7 +3967,7 @@ time_mday(VALUE time)
314
  *     time.mon   -> fixnum
315
  *     time.month -> fixnum
316
  *
317
- *  Returns the month of the year (1..12) for <i>time</i>.
318
+ *  Returns the month of the year (1..12) for _time_.
319
  *
320
  *     t = Time.now   #=> 2007-11-19 08:27:30 -0600
321
  *     t.mon          #=> 11
322
@@ -3991,7 +3988,7 @@ time_mon(VALUE time)
323
  *  call-seq:
324
  *     time.year -> fixnum
325
  *
326
- *  Returns the year for <i>time</i> (including the century).
327
+ *  Returns the year for _time_ (including the century).
328
  *
329
  *     t = Time.now   #=> 2007-11-19 08:27:51 -0600
330
  *     t.year         #=> 2007
331
@@ -4046,7 +4043,7 @@ time_wday(VALUE time)
332
  *  call-seq:
333
  *     time.sunday? -> true or false
334
  *
335
- *  Returns <code>true</code> if <i>time</i> represents Sunday.
336
+ *  Returns +true+ if _time_ represents Sunday.
337
  *
338
  *     t = Time.local(1990, 4, 1)       #=> 1990-04-01 00:00:00 -0600
339
  *     t.sunday?                        #=> true
340
@@ -4062,7 +4059,7 @@ time_sunday(VALUE time)
341
  *  call-seq:
342
  *     time.monday? -> true or false
343
  *
344
- *  Returns <code>true</code> if <i>time</i> represents Monday.
345
+ *  Returns +true+ if _time_ represents Monday.
346
  *
347
  *     t = Time.local(2003, 8, 4)       #=> 2003-08-04 00:00:00 -0500
348
  *     p t.monday?                      #=> true
349
@@ -4078,7 +4075,7 @@ time_monday(VALUE time)
350
  *  call-seq:
351
  *     time.tuesday? -> true or false
352
  *
353
- *  Returns <code>true</code> if <i>time</i> represents Tuesday.
354
+ *  Returns +true+ if _time_ represents Tuesday.
355
  *
356
  *     t = Time.local(1991, 2, 19)      #=> 1991-02-19 00:00:00 -0600
357
  *     p t.tuesday?                     #=> true
358
@@ -4094,7 +4091,7 @@ time_tuesday(VALUE time)
359
  *  call-seq:
360
  *     time.wednesday? -> true or false
361
  *
362
- *  Returns <code>true</code> if <i>time</i> represents Wednesday.
363
+ *  Returns +true+ if _time_ represents Wednesday.
364
  *
365
  *     t = Time.local(1993, 2, 24)      #=> 1993-02-24 00:00:00 -0600
366
  *     p t.wednesday?                   #=> true
367
@@ -4110,7 +4107,7 @@ time_wednesday(VALUE time)
368
  *  call-seq:
369
  *     time.thursday? -> true or false
370
  *
371
- *  Returns <code>true</code> if <i>time</i> represents Thursday.
372
+ *  Returns +true+ if _time_ represents Thursday.
373
  *
374
  *     t = Time.local(1995, 12, 21)     #=> 1995-12-21 00:00:00 -0600
375
  *     p t.thursday?                    #=> true
376
@@ -4126,7 +4123,7 @@ time_thursday(VALUE time)
377
  *  call-seq:
378
  *     time.friday? -> true or false
379
  *
380
- *  Returns <code>true</code> if <i>time</i> represents Friday.
381
+ *  Returns +true+ if _time_ represents Friday.
382
  *
383
  *     t = Time.local(1987, 12, 18)     #=> 1987-12-18 00:00:00 -0600
384
  *     t.friday?                        #=> true
385
@@ -4142,7 +4139,7 @@ time_friday(VALUE time)
386
  *  call-seq:
387
  *     time.saturday? -> true or false
388
  *
389
- *  Returns <code>true</code> if <i>time</i> represents Saturday.
390
+ *  Returns +true+ if _time_ represents Saturday.
391
  *
392
  *     t = Time.local(2006, 6, 10)      #=> 2006-06-10 00:00:00 -0500
393
  *     t.saturday?                      #=> true
394
@@ -4179,7 +4176,7 @@ time_yday(VALUE time)
395
  *     time.isdst -> true or false
396
  *     time.dst?  -> true or false
397
  *
398
- *  Returns <code>true</code> if <i>time</i> occurs during Daylight
399
+ *  Returns +true+ if _time_ occurs during Daylight
400
  *  Saving Time in its time zone.
401
  *
402
  *   # CST6CDT:
403
@@ -4213,7 +4210,7 @@ time_isdst(VALUE time)
404
  *  call-seq:
405
  *     time.zone -> string
406
  *
407
- *  Returns the name of the time zone used for <i>time</i>. As of Ruby
408
+ *  Returns the name of the time zone used for _time_. As of Ruby
409
  *  1.8, returns ``UTC'' rather than ``GMT'' for UTC times.
410
  *
411
  *     t = Time.gm(2000, "jan", 1, 20, 15, 1)
412
@@ -4244,7 +4241,7 @@ time_zone(VALUE time)
413
  *     time.gmtoff     -> fixnum
414
  *     time.utc_offset -> fixnum
415
  *
416
- *  Returns the offset in seconds between the timezone of <i>time</i>
417
+ *  Returns the offset in seconds between the timezone of _time_
418
  *  and UTC.
419
  *
420
  *     t = Time.gm(2000,1,1,20,15,1)   #=> 2000-01-01 20:15:01 UTC
421
@@ -4273,12 +4270,14 @@ time_utc_offset(VALUE time)
422
  *  call-seq:
423
  *     time.to_a -> array
424
  *
425
- *  Returns a ten-element <i>array</i> of values for <i>time</i>:
426
- *  {<code>[ sec, min, hour, day, month, year, wday, yday, isdst, zone
427
- *  ]</code>}. See the individual methods for an explanation of the
428
+ *  Returns a ten-element _array_ of values for _time_:
429
+ *
430
+ *     [sec, min, hour, day, month, year, wday, yday, isdst, zone]
431
+ *
432
+ *  See the individual methods for an explanation of the
433
  *  valid ranges of each value. The ten elements can be passed directly
434
- *  to <code>Time::utc</code> or <code>Time::local</code> to create a
435
- *  new <code>Time</code>.
436
+ *  to Time::utc or Time::local to create a
437
+ *  new Time object.
438
  *
439
  *     t = Time.now     #=> 2007-11-19 08:36:01 -0600
440
  *     now = t.to_a     #=> [1, 36, 8, 19, 11, 2007, 1, 323, false, "CST"]
441
@@ -4372,30 +4371,30 @@ strftimev(const char *fmt, VALUE time, rb_encoding *enc)
442
  *  call-seq:
443
  *     time.strftime( string ) -> string
444
  *
445
- *  Formats <i>time</i> according to the directives in the given format
446
- *  string.
447
- *  The directives begins with a percent (%) character.
448
+ *  Formats _time_ according to the directives in the given format string.
449
+ *
450
+ *  The directives begin with a percent (%) character.
451
  *  Any text not listed as a directive will be passed through to the
452
  *  output string.
453
  *
454
  *  The directive consists of a percent (%) character,
455
  *  zero or more flags, optional minimum field width,
456
  *  optional modifier and a conversion specifier
457
- *  as follows.
458
+ *  as follows:
459
  *
460
  *    %<flags><width><modifier><conversion>
461
  *
462
  *  Flags:
463
- *    -  don't pad a numerical output.
464
- *    _  use spaces for padding.
465
- *    0  use zeros for padding.
466
- *    ^  upcase the result string.
467
- *    #  change case.
468
- *    :  use colons for %z.
469
+ *    -  don't pad a numerical output
470
+ *    _  use spaces for padding
471
+ *    0  use zeros for padding
472
+ *    ^  upcase the result string
473
+ *    #  change case
474
+ *    :  use colons for %z
475
  *
476
  *  The minimum field width specifies the minimum width.
477
  *
478
- *  The modifier is "E" and "O".
479
+ *  The modifiers are "E" and "O".
480
  *  They are ignored.
481
  *
482
  *  Format directives:
483
@@ -4849,7 +4848,7 @@ end_submicro: ;
484
  * call-seq:
485
  *   Time._load(string)   -> time
486
  *
487
- * Unmarshal a dumped +Time+ object.
488
+ * Unmarshal a dumped Time object.
489
  */
490
 
491
 static VALUE
492
@@ -4873,7 +4872,8 @@ time_load(VALUE klass, VALUE str)
493
  *  with each other -- times that are apparently equal when displayed may be
494
  *  different when compared.
495
  *
496
- *  Since Ruby 1.9.2, Time implementation uses a signed 63 bit integer, Bignum or Rational.
497
+ *  Since Ruby 1.9.2, Time implementation uses a signed 63 bit integer,
498
+ *  Bignum or Rational.
499
  *  The integer is a number of nanoseconds since the _Epoch_ which can
500
  *  represent 1823-11-12 to 2116-02-20.
501
  *  When Bignum or Rational is used (before 1823, after 2116, under nanosecond),
502
@@ -4885,9 +4885,9 @@ time_load(VALUE klass, VALUE str)
503
  *
504
  *  == Creating a new Time instance
505
  *
506
- *  You can create a new instance of time with Time.new. This will use the
507
- *  current system time. Time.now is a synonym for this. You can also
508
- *  pass parts of the time to Time.new such as year, month, minute, etc. When
509
+ *  You can create a new instance of Time with Time::new. This will use the
510
+ *  current system time. Time::now is an alias for this. You can also
511
+ *  pass parts of the time to Time::new such as year, month, minute, etc. When
512
  *  you want to construct a time this way you must pass at least a year. If you
513
  *  pass the year with nothing else time with default to January 1 of that year
514
  *  at 00:00:00 with the current system timezone. Here are some examples:
515
@@ -4900,7 +4900,7 @@ time_load(VALUE klass, VALUE str)
516
  *  You can also use #gm, #local and #utc to infer GMT, local and UTC
517
  *  timezones instead of using the current system setting.
518
  *
519
- *  You can also create a new time using Time.at which takes the number of
520
+ *  You can also create a new time using Time::at which takes the number of
521
  *  seconds (or fraction of seconds) since the {Unix
522
  *  Epoch}[http://en.wikipedia.org/wiki/Unix_time].
523
  *
524
@@ -4908,8 +4908,8 @@ time_load(VALUE klass, VALUE str)
525
  *
526
  *  == Working with an instance of Time
527
  *
528
- *  Once you have an instance of time there is a multitude of things you can do
529
- *  with it. Below are some examples. For all of the following examples, we
530
+ *  Once you have an instance of Time there is a multitude of things you can
531
+ *  do with it. Below are some examples. For all of the following examples, we
532
  *  will work on the assumption that you have done the following:
533
  *
534
  *    t = Time.new(1993, 02, 24, 12, 0, 0, "+09:00")
535
-- 
536
1.7.11.1
537

  
time_patch0003.diff
1
From 98a8afe3f80d82ffddacd7eaf4bbc16c72d9f2be Mon Sep 17 00:00:00 2001
2
From: Bernd Homuth <dev@hmt.im>
3
Date: Sat, 24 Nov 2012 10:58:26 +0100
4
Subject: [PATCH] changes to time.c docs
5

  
6
---
7
 time.c | 87 ++++++++++++++++++++++++++++++++++++------------------------------
8
 1 file changed, 47 insertions(+), 40 deletions(-)
9

  
10
diff --git a/time.c b/time.c
11
index 97d37ed..592965e 100644
12
--- a/time.c
13
+++ b/time.c
14
@@ -2222,10 +2222,10 @@ time_init_1(int argc, VALUE *argv, VALUE time)
15
  *
16
  *  Returns a Time object.
17
  *
18
- *  It is initialized to the current system time if no argument.
19
- *  <b>Note:</b> The object created will be created using the
20
- *  resolution available on your system clock, and so may include
21
- *  fractional seconds.
22
+ *  It is initialized to the current system time if no argument is given.
23
+ *
24
+ *  *Note:* The new object will use the resolution available on your
25
+ *  system clock, and may include fractional seconds.
26
  *
27
  *  If one or more arguments specified, the time is initialized
28
  *  to the specified time.
29
@@ -3118,7 +3118,7 @@ time_utc_or_local(int argc, VALUE *argv, int utc_p, VALUE klass)
30
  *    Time.gm(year, month, day, hour, min, sec, usec_with_frac) -> time
31
  *    Time.gm(sec, min, hour, day, month, year, wday, yday, isdst, tz) -> time
32
  *
33
- *  Creates a time based on given values, interpreted as UTC (GMT). The
34
+ *  Creates a Time object based on given values, interpreted as UTC (GMT). The
35
  *  year must be specified. Other values default to the minimum value
36
  *  for that field (and may be +nil+ or omitted). Months may
37
  *  be specified by numbers from 1 to 12, or by the three-letter English
38
@@ -3281,8 +3281,9 @@ time_usec(VALUE time)
39
  *
40
  *  The lowest digits of #to_f and #nsec are different because
41
  *  IEEE 754 double is not accurate enough to represent
42
- *  nanoseconds from the Epoch.
43
- *  The accurate value is returned by nsec.
44
+ *  the exact number of nanoseconds since the Epoch.
45
+ *
46
+ *  The more accurate value is returned by #nsec.
47
  */
48
 
49
 static VALUE
50
@@ -3300,7 +3301,7 @@ time_nsec(VALUE time)
51
  *
52
  *  Returns the fraction for _time_.
53
  *
54
- *  The result is possibly rational.
55
+ *  The return value can be a rational number.
56
  *
57
  *     t = Time.now        #=> 2009-03-26 22:33:12 +0900
58
  *     "%10.9f" % t.to_f   #=> "1238074392.940563917"
59
@@ -3308,8 +3309,9 @@ time_nsec(VALUE time)
60
  *
61
  *  The lowest digits of #to_f and #subsec are different because
62
  *  IEEE 754 double is not accurate enough to represent
63
- *  the rational.
64
- *  The accurate value is returned by subsec.
65
+ *  the rational number.
66
+ *
67
+ *  The more accurate value is returned by #subsec.
68
  */
69
 
70
 static VALUE
71
@@ -3325,7 +3327,10 @@ time_subsec(VALUE time)
72
  *  call-seq:
73
  *     time <=> other_time -> -1, 0, +1 or nil
74
  *
75
- *  Comparison---Compares <i>time</i> with <i>other_time</i>.
76
+ *  Comparison---Compares _time_ with +other_time+.
77
+ *  The return value is ++1+ if _time_ is greater than
78
+ *  +other_time+, +0+ if _time_ is equal to +other_time+ and
79
+ *  +-1+ if _time_ is smaller than +other_time+.
80
  *
81
  *     t = Time.now       #=> 2007-11-19 08:12:12 -0600
82
  *     t2 = t + 2592000   #=> 2007-12-19 08:12:12 -0600
83
@@ -3678,15 +3683,15 @@ time_asctime(VALUE time)
84
  *     time.inspect -> string
85
  *     time.to_s    -> string
86
  *
87
- *  Returns a string representing <i>time</i>. Equivalent to calling
88
- *  <code>Time#strftime</code> with a format string of
89
- *  ``<code>%Y-%m-%d</code> <code>%H:%M:%S</code> <code>%z</code>''
90
- *  for a local time and
91
- *  ``<code>%Y-%m-%d</code> <code>%H:%M:%S</code> <code>UTC</code>''
92
- *  for a UTC time.
93
+ *  Returns a string representing _time_. Equivalent to calling
94
+ *  #strftime with the appropriate format string.
95
+ *
96
+ *     t = Time.now
97
+ *     t.to_s                              => "2012-11-10 18:16:12 +0100"
98
+ *     t.strftime "%Y-%m-%d %H:%M:%S %z"   => "2012-11-10 18:16:12 +0100"
99
  *
100
- *     Time.now.to_s       #=> "2007-10-05 16:09:51 +0900"
101
- *     Time.now.utc.to_s   #=> "2007-10-05 07:09:51 UTC"
102
+ *     t.utc.to_s                          => "2012-11-10 17:16:12 UTC"
103
+ *     t.strftime "%Y-%m-%d %H:%M:%S UTC"  => "2012-11-10 17:16:12 UTC"
104
  */
105
 
106
 static VALUE
107
@@ -3750,9 +3755,9 @@ time_plus(VALUE time1, VALUE time2)
108
  *     time - other_time -> float
109
  *     time - numeric    -> time
110
  *
111
- *  Difference---Returns a new time that represents the difference
112
- *  between two times, or subtracts the given number of seconds in
113
- *  <i>numeric</i> from <i>time</i>.
114
+ *  Difference---Returns a new Time object that represents the difference
115
+ *  between _time_ and +other_time+, or subtracts the given number
116
+ *  of seconds in +numeric+ from _time_.
117
  *
118
  *     t = Time.now       #=> 2007-11-19 08:23:10 -0600
119
  *     t2 = t + 2592000   #=> 2007-12-19 08:23:10 -0600
120
@@ -3784,6 +3789,10 @@ time_minus(VALUE time1, VALUE time2)
121
  *
122
  *     t = Time.now       #=> 2007-11-19 08:23:57 -0600
123
  *     t.succ             #=> 2007-11-19 08:23:58 -0600
124
+ *
125
+ * Use instead <code>time + 1</code>
126
+ *
127
+ *     t + 1              #=> 2007-11-19 08:23:58 -0600
128
  */
129
 
130
 VALUE
131
@@ -3882,9 +3891,9 @@ time_round(int argc, VALUE *argv, VALUE time)
132
  *
133
  *  Returns the second of the minute (0..60) for _time_.
134
  *
135
- *  <em>[Yes, seconds range from zero to 60.  This allows the system to inject
136
- *  leap seconds.  See http://en.wikipedia.org/wiki/Leap_second for further
137
- *  details.]</em>
138
+ *  *Note:* Seconds range from zero to 60 to allow the system to inject
139
+ *  leap seconds. See http://en.wikipedia.org/wiki/Leap_second for further
140
+ *  details.
141
  *
142
  *     t = Time.now   #=> 2007-11-19 08:25:02 -0600
143
  *     t.sec          #=> 2
144
@@ -4402,7 +4411,7 @@ strftimev(const char *fmt, VALUE time, rb_encoding *enc)
145
  *    Date (Year, Month, Day):
146
  *      %Y - Year with century (can be negative, 4 digits at least)
147
  *              -0001, 0000, 1995, 2009, 14292, etc.
148
- *      %C - year / 100 (round down.  20 in 2009)
149
+ *      %C - year / 100 (rounded down such as 20 in 2009)
150
  *      %y - year % 100 (00..99)
151
  *
152
  *      %m - Month of the year, zero-padded (01..12)
153
@@ -4491,21 +4500,18 @@ strftimev(const char *fmt, VALUE time, rb_encoding *enc)
154
  *      %T - 24-hour time (%H:%M:%S)
155
  *
156
  *  This method is similar to strftime() function defined in ISO C and POSIX.
157
- *  Several directives (%a, %A, %b, %B, %c, %p, %r, %x, %X, %E*, %O* and %Z)
158
- *  are locale dependent in the function.
159
- *  However this method is locale independent since Ruby 1.9.
160
- *  (%Z is platform dependent, though.)
161
- *  So, the result may differ even if a same format string is used in other
162
+ *
163
+ *  While all directives are locale independant since Ruby 1.9 %Z is platform
164
+ *  dependant.
165
+ *  So, the result may differ even if the same format string is used in other
166
  *  systems such as C.
167
- *  It is good practice to avoid %x and %X because there are corresponding
168
- *  locale independent representations, %D and %T.
169
  *
170
  *  %z is recommended over %Z.
171
  *  %Z doesn't identify the timezone.
172
  *  For example, "CST" is used at America/Chicago (-06:00),
173
  *  America/Havana (-05:00), Asia/Harbin (+08:00), Australia/Darwin (+09:30)
174
  *  and Australia/Adelaide (+10:30).
175
- *  Also, %Z is highly dependent for OS.
176
+ *  Also, %Z is highly dependent on the operating system.
177
  *  For example, it may generate a non ASCII string on Japanese Windows.
178
  *  i.e. the result can be different to "JST".
179
  *  So the numeric time zone offset, %z, is recommended.
180
@@ -4863,7 +4869,7 @@ time_load(VALUE klass, VALUE str)
181
 /*
182
  *  Time is an abstraction of dates and times. Time is stored internally as
183
  *  the number of seconds with fraction since the _Epoch_, January 1, 1970
184
- *  00:00 UTC. Also see the library modules Date. The Time class treats GMT
185
+ *  00:00 UTC. Also see the library module Date. The Time class treats GMT
186
  *  (Greenwich Mean Time) and UTC (Coordinated Universal Time) as equivalent.
187
  *  GMT is the older way of referring to these baseline times but persists in
188
  *  the names of calls on POSIX systems.
189
@@ -4876,8 +4882,8 @@ time_load(VALUE klass, VALUE str)
190
  *  Bignum or Rational.
191
  *  The integer is a number of nanoseconds since the _Epoch_ which can
192
  *  represent 1823-11-12 to 2116-02-20.
193
- *  When Bignum or Rational is used (before 1823, after 2116, under nanosecond),
194
- *  Time works slower than the integer is used.
195
+ *  When Bignum or Rational is used (before 1823, after 2116, under
196
+ *  nanosecond), Time works slower as when integer is used.
197
  *
198
  *  = Examples
199
  *
200
@@ -4889,7 +4895,7 @@ time_load(VALUE klass, VALUE str)
201
  *  current system time. Time::now is an alias for this. You can also
202
  *  pass parts of the time to Time::new such as year, month, minute, etc. When
203
  *  you want to construct a time this way you must pass at least a year. If you
204
- *  pass the year with nothing else time with default to January 1 of that year
205
+ *  pass the year with nothing else time will default to January 1 of that year
206
  *  at 00:00:00 with the current system timezone. Here are some examples:
207
  *
208
  *    Time.new(2002)         #=> 2002-01-01 00:00:00 -0500
209
@@ -4897,8 +4903,9 @@ time_load(VALUE klass, VALUE str)
210
  *    Time.new(2002, 10, 31) #=> 2002-10-31 00:00:00 -0500
211
  *    Time.new(2002, 10, 31, 2, 2, 2, "+02:00") #=> 2002-10-31 02:02:02 -0200
212
  *
213
- *  You can also use #gm, #local and #utc to infer GMT, local and UTC
214
- *  timezones instead of using the current system setting.
215
+ *  You can also use #gm, #local and
216
+ *  #utc to infer GMT, local and UTC timezones instead of using
217
+ *  the current system setting.
218
  *
219
  *  You can also create a new time using Time::at which takes the number of
220
  *  seconds (or fraction of seconds) since the {Unix
221
-- 
222
1.7.11.1
223

  
0
-