[DOC] Enhanced RDoc for Time (#6320)

Treats:
    #yday
    #dst?
    #zone
    #to_a
    #strftime

1 files changed, 36 insertions, 231 deletions

diff --git a/time.c b/time.c
index a02e53d7f1..26083b0d5d 100644
--- a/time.c
+++ b/time.c
@@ -4685,12 +4685,12 @@ time_saturday(VALUE time)
 
 /*
  *  call-seq:
- *     time.yday -> integer
+ *    yday -> integer
  *
- *  Returns an integer representing the day of the year, 1..366.
+ *  Returns the integer day of the year of +self+, in range (1..366).
  *
- *     t = Time.now   #=> 2007-11-19 08:32:31 -0600
- *     t.yday         #=> 323
+ *    Time.new(2000, 1, 1).yday   # => 1
+ *    Time.new(2000, 12, 31).yday # => 366
  */
 
 static VALUE
@@ -4705,27 +4705,18 @@ time_yday(VALUE time)
 
 /*
  *  call-seq:
- *     time.isdst -> true or false
- *     time.dst?  -> true or false
- *
- *  Returns +true+ if _time_ occurs during Daylight
- *  Saving Time in its time zone.
- *
- *   # CST6CDT:
- *     Time.local(2000, 1, 1).zone    #=> "CST"
- *     Time.local(2000, 1, 1).isdst   #=> false
- *     Time.local(2000, 1, 1).dst?    #=> false
- *     Time.local(2000, 7, 1).zone    #=> "CDT"
- *     Time.local(2000, 7, 1).isdst   #=> true
- *     Time.local(2000, 7, 1).dst?    #=> true
- *
- *   # Asia/Tokyo:
- *     Time.local(2000, 1, 1).zone    #=> "JST"
- *     Time.local(2000, 1, 1).isdst   #=> false
- *     Time.local(2000, 1, 1).dst?    #=> false
- *     Time.local(2000, 7, 1).zone    #=> "JST"
- *     Time.local(2000, 7, 1).isdst   #=> false
- *     Time.local(2000, 7, 1).dst?    #=> false
+ *    dst?  -> true or false
+ *
+ *  Returns +true+ if +self+ is in daylight saving time, +false+ otherwise:
+ *
+ *    t = Time.local(2000, 1, 1) # => 2000-01-01 00:00:00 -0600
+ *    t.zone                     # => "Central Standard Time"
+ *    t.dst?                     # => false
+ *    t = Time.local(2000, 7, 1) # => 2000-07-01 00:00:00 -0500
+ *    t.zone                     # => "Central Daylight Time"
+ *    t.dst?                     # => true
+ *
+ *    Time#isdst is an alias for Time#dst?.
  */
 
 static VALUE
@@ -4745,13 +4736,10 @@ time_isdst(VALUE time)
  *  call-seq:
  *     time.zone -> string or timezone
  *
- *  Returns the name of the time zone used for _time_. As of Ruby
- *  1.8, returns ``UTC'' rather than ``GMT'' for UTC times.
+ *  Returns the string name of the time zone for +self+:
  *
- *     t = Time.gm(2000, "jan", 1, 20, 15, 1)
- *     t.zone   #=> "UTC"
- *     t = Time.local(2000, "jan", 1, 20, 15, 1)
- *     t.zone   #=> "CST"
+ *    Time.utc(2000, 1, 1).zone # => "UTC"
+ *    Time.new(2000, 1, 1).zone # => "Central Standard Time"
  */
 
 static VALUE
@@ -4777,17 +4765,14 @@ time_zone(VALUE time)
 
 /*
  *  call-seq:
- *     time.gmt_offset -> integer
- *     time.gmtoff     -> integer
- *     time.utc_offset -> integer
+ *    utc_offset -> integer
+ *
+ *  Returns the offset in seconds between the timezones of UTC and +self+:
  *
- *  Returns the offset in seconds between the timezone of _time_
- *  and UTC.
+ *    Time.utc(2000, 1, 1).utc_offset   # => 0
+ *    Time.local(2000, 1, 1).utc_offset # => -21600 # -6*3600, or minus six hours.
  *
- *     t = Time.gm(2000,1,1,20,15,1)   #=> 2000-01-01 20:15:01 UTC
- *     t.gmt_offset                    #=> 0
- *     l = t.getlocal                  #=> 2000-01-01 14:15:01 -0600
- *     l.gmt_offset                    #=> -21600
+ *  Time#gmt_offset and Time#gmtoff are aliases for Time#utc_offset.
  */
 
 VALUE
@@ -4808,19 +4793,17 @@ rb_time_utc_offset(VALUE time)
 
 /*
  *  call-seq:
- *     time.to_a -> array
+ *    to_a -> array
  *
- *  Returns a ten-element _array_ of values for _time_:
+ *  Returns a 10-element array of values representing +self+:
  *
- *     [sec, min, hour, day, month, year, wday, yday, isdst, zone]
+ *    Time.utc(2000, 1, 1).to_a
+ *    # => [0,   0,   0,    1,   1,   2000, 6,    1,    false, "UTC"]
+ *    #    [sec, min, hour, day, mon, year, wday, yday, dst?,   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 object.
+ *  The returned array is suitable for use as an argument 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"]
  */
 
 static VALUE
@@ -4876,189 +4859,11 @@ strftime_cstr(const char *fmt, size_t len, VALUE time, rb_encoding *enc)
 
 /*
  *  call-seq:
- *     time.strftime( string ) -> string
- *
- *  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:
- *
- *    %<flags><width><modifier><conversion>
- *
- *  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
- *
- *  The minimum field width specifies the minimum width.
- *
- *  The modifiers are "E" and "O".
- *  They are ignored.
- *
- *  Format directives:
- *
- *    Date (Year, Month, Day):
- *      %Y - Year with century if provided, will pad result at least 4 digits.
- *              -0001, 0000, 1995, 2009, 14292, etc.
- *      %C - year / 100 (rounded down such as 20 in 2009)
- *      %y - year % 100 (00..99)
- *
- *      %m - Month of the year, zero-padded (01..12)
- *              %_m  blank-padded ( 1..12)
- *              %-m  no-padded (1..12)
- *      %B - The full month name (``January'')
- *              %^B  uppercased (``JANUARY'')
- *      %b - The abbreviated month name (``Jan'')
- *              %^b  uppercased (``JAN'')
- *      %h - Equivalent to %b
- *
- *      %d - Day of the month, zero-padded (01..31)
- *              %-d  no-padded (1..31)
- *      %e - Day of the month, blank-padded ( 1..31)
- *
- *      %j - Day of the year (001..366)
- *
- *    Time (Hour, Minute, Second, Subsecond):
- *      %H - Hour of the day, 24-hour clock, zero-padded (00..23)
- *      %k - Hour of the day, 24-hour clock, blank-padded ( 0..23)
- *      %I - Hour of the day, 12-hour clock, zero-padded (01..12)
- *      %l - Hour of the day, 12-hour clock, blank-padded ( 1..12)
- *      %P - Meridian indicator, lowercase (``am'' or ``pm'')
- *      %p - Meridian indicator, uppercase (``AM'' or ``PM'')
- *
- *      %M - Minute of the hour (00..59)
- *
- *      %S - Second of the minute (00..60)
- *
- *      %L - Millisecond of the second (000..999)
- *           The digits under millisecond are truncated to not produce 1000.
- *      %N - Fractional seconds digits, default is 9 digits (nanosecond)
- *              %3N  millisecond (3 digits)
- *              %6N  microsecond (6 digits)
- *              %9N  nanosecond (9 digits)
- *              %12N picosecond (12 digits)
- *              %15N femtosecond (15 digits)
- *              %18N attosecond (18 digits)
- *              %21N zeptosecond (21 digits)
- *              %24N yoctosecond (24 digits)
- *           The digits under the specified length are truncated to avoid
- *           carry up.
- *
- *    Time zone:
- *      %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 - Abbreviated time zone name or similar information.  (OS dependent)
- *
- *    Weekday:
- *      %A - The full weekday name (``Sunday'')
- *              %^A  uppercased (``SUNDAY'')
- *      %a - The abbreviated name (``Sun'')
- *              %^a  uppercased (``SUN'')
- *      %u - Day of the week (Monday is 1, 1..7)
- *      %w - Day of the week (Sunday is 0, 0..6)
- *
- *    ISO 8601 week-based year and week number:
- *    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
- *      %g - The last 2 digits of the week-based year (00..99)
- *      %V - Week number of the week-based year (01..53)
- *
- *    Week number:
- *    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.
- *
- *    Literal string:
- *      %n - Newline character (\n)
- *      %t - Tab character (\t)
- *      %% - Literal ``%'' character
- *
- *    Combination:
- *      %c - date and time (%a %b %e %T %Y)
- *      %D - Date (%m/%d/%y)
- *      %F - The ISO 8601 date format (%Y-%m-%d)
- *      %v - VMS date (%e-%^b-%4Y)
- *      %x - Same as %D
- *      %X - Same as %T
- *      %r - 12-hour time (%I:%M:%S %p)
- *      %R - 24-hour time (%H:%M)
- *      %T - 24-hour time (%H:%M:%S)
- *
- *  This method is similar to strftime() function defined in ISO C and POSIX.
- *
- *  While all directives are locale independent since Ruby 1.9, %Z is platform
- *  dependent.
- *  So, the result may differ even if the same format string is used in other
- *  systems such as C.
- *
- *  %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 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.
- *
- *  Examples:
- *
- *    t = Time.new(2007,11,19,8,37,48,"-06:00") #=> 2007-11-19 08:37:48 -0600
- *    t.strftime("Printed on %m/%d/%Y")         #=> "Printed on 11/19/2007"
- *    t.strftime("at %I:%M %p")                 #=> "at 08:37 AM"
- *
- *  Various ISO 8601 formats:
- *    %Y%m%d           => 20071119                  Calendar date (basic)
- *    %F               => 2007-11-19                Calendar date (extended)
- *    %Y-%m            => 2007-11                   Calendar date, reduced accuracy, specific month
- *    %Y               => 2007                      Calendar date, reduced accuracy, specific year
- *    %C               => 20                        Calendar date, reduced accuracy, specific century
- *    %Y%j             => 2007323                   Ordinal date (basic)
- *    %Y-%j            => 2007-323                  Ordinal date (extended)
- *    %GW%V%u          => 2007W471                  Week date (basic)
- *    %G-W%V-%u        => 2007-W47-1                Week date (extended)
- *    %GW%V            => 2007W47                   Week date, reduced accuracy, specific week (basic)
- *    %G-W%V           => 2007-W47                  Week date, reduced accuracy, specific week (extended)
- *    %H%M%S           => 083748                    Local time (basic)
- *    %T               => 08:37:48                  Local time (extended)
- *    %H%M             => 0837                      Local time, reduced accuracy, specific minute (basic)
- *    %H:%M            => 08:37                     Local time, reduced accuracy, specific minute (extended)
- *    %H               => 08                        Local time, reduced accuracy, specific hour
- *    %H%M%S,%L        => 083748,000                Local time with decimal fraction, comma as decimal sign (basic)
- *    %T,%L            => 08:37:48,000              Local time with decimal fraction, comma as decimal sign (extended)
- *    %H%M%S.%L        => 083748.000                Local time with decimal fraction, full stop as decimal sign (basic)
- *    %T.%L            => 08:37:48.000              Local time with decimal fraction, full stop as decimal sign (extended)
- *    %H%M%S%z         => 083748-0600               Local time and the difference from UTC (basic)
- *    %T%:z            => 08:37:48-06:00            Local time and the difference from UTC (extended)
- *    %Y%m%dT%H%M%S%z  => 20071119T083748-0600      Date and time of day for calendar date (basic)
- *    %FT%T%:z         => 2007-11-19T08:37:48-06:00 Date and time of day for calendar date (extended)
- *    %Y%jT%H%M%S%z    => 2007323T083748-0600       Date and time of day for ordinal date (basic)
- *    %Y-%jT%T%:z      => 2007-323T08:37:48-06:00   Date and time of day for ordinal date (extended)
- *    %GW%V%uT%H%M%S%z => 2007W471T083748-0600      Date and time of day for week date (basic)
- *    %G-W%V-%uT%T%:z  => 2007-W47-1T08:37:48-06:00 Date and time of day for week date (extended)
- *    %Y%m%dT%H%M      => 20071119T0837             Calendar date and local time (basic)
- *    %FT%R            => 2007-11-19T08:37          Calendar date and local time (extended)
- *    %Y%jT%H%MZ       => 2007323T0837Z             Ordinal date and UTC of day (basic)
- *    %Y-%jT%RZ        => 2007-323T08:37Z           Ordinal date and UTC of day (extended)
- *    %GW%V%uT%H%M%z   => 2007W471T0837-0600        Week date and local time and difference from UTC (basic)
- *    %G-W%V-%uT%R%:z  => 2007-W47-1T08:37-06:00    Week date and local time and difference from UTC (extended)
+ *    strftime(format_string) -> string
  *
+ *  Returns a string representation of +self+,
+ *  formatted according to the given string +format+.
+ *  See {Formats for Dates and Times}[rdoc-ref:doc/strftime_formatting.rdoc].
  */
 
 static VALUE