[DOC] Enhanced RDoc for Time (#6308)

More on timezones.

doc/timezone_specifiers.rdoc

@@ -1,46 +0,0 @@
-=== Timezone Specifiers
-
-Certain methods in class Time accept arguments that specify timezones:
-
-- Time.at: keyword argument +in:+.
-- Time.new: positional argument +zone+ or keyword argument +in:+.
-- Time.now: keyword argument +in:+.
-- Time#getlocal: positional argument +zone+.
-- Time#localtime: positional argument +zone+.
-
-The value given with any of these must be one of the following:
-
-- A string offset from UTC in the form <tt>'+HH:MM'</tt> or <tt>-HH:MM</tt>,
-  where:
-
-  - +HH+ is the 2-digit hour in the range <tt>0..23</tt>.
-  - +MM+ is the 2-digit minute in the range <tt>0..59</tt>.
-
-  Examples:
-
-    t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC
-    Time.at(t, in: '-23:59')            # => 1999-12-31 20:16:01 -2359
-    Time.at(t, in: '+23:59')            # => 2000-01-02 20:14:01 +2359
-
-- A letter in the range <tt>'A'..'I'</tt> or <tt>'K'..'Z'</tt>;
-  see {List of military time zones}[https://en.wikipedia.org/wiki/List_of_military_time_zones]:
-
-    t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC
-    Time.at(t, in: 'A')                 # => 2000-01-01 21:15:01 +0100
-    Time.at(t, in: 'I')                 # => 2000-01-02 05:15:01 +0900
-    Time.at(t, in: 'K')                 # => 2000-01-02 06:15:01 +1000
-    Time.at(t, in: 'Y')                 # => 2000-01-01 08:15:01 -1200
-    Time.at(t, in: 'Z')                 # => 2000-01-01 20:15:01 UTC
-
-- An integer number of seconds in the range <tt>-86399..86399</tt>:
-
-    t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC
-    Time.at(t, in: -86399)              # => 1999-12-31 20:15:02 -235959
-    Time.at(t, in: 86399)               # => 2000-01-02 20:15:00 +235959
-
---
-TODO:  Pull in and revise the text at the link,
-then add the example class TZ from the tests.
-++
-- A timezone object;
-  see {Timezone Argument}[rdoc-ref:Time@Timezone+Argument] for details.

doc/timezones.rdoc

@@ -0,0 +1,108 @@
+== Timezones
+
+=== Timezone Specifiers
+
+Certain \Time methods accept arguments that specify timezones:
+
+- Time.at: keyword argument +in:+.
+- Time.new: positional argument +zone+ or keyword argument +in:+.
+- Time.now: keyword argument +in:+.
+- Time#getlocal: positional argument +zone+.
+- Time#localtime: positional argument +zone+.
+
+The value given with any of these must be one of the following
+(each detailed below):
+
+- {Hours/minutes offset}[rdoc-ref:timezones.rdoc@Hours-2FMinutes+Offsets].
+- {Single-letter offset}[rdoc-ref:timezones.rdoc@Single-Letter+Offsets].
+- {Integer offset}[rdoc-ref:timezones.rdoc@Integer+Offsets].
+- {Timezone object}[rdoc-ref:timezones.rdoc@Timezone+Objects].
+
+==== Hours/Minutes Offsets
+
+The zone value may be a string offset from UTC
+in the form <tt>'+HH:MM'</tt> or <tt>'-HH:MM'</tt>,
+where:
+
+- +HH+ is the 2-digit hour in the range <tt>0..23</tt>.
+- +MM+ is the 2-digit minute in the range <tt>0..59</tt>.
+
+Examples:
+
+  t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC
+  Time.at(t, in: '-23:59')            # => 1999-12-31 20:16:01 -2359
+  Time.at(t, in: '+23:59')            # => 2000-01-02 20:14:01 +2359
+
+==== Single-Letter Offsets
+
+The zone value may be a  letter in the range <tt>'A'..'I'</tt>
+or <tt>'K'..'Z'</tt>;
+see {List of military time zones}[https://en.wikipedia.org/wiki/List_of_military_time_zones]:
+
+  t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC
+  Time.at(t, in: 'A')                 # => 2000-01-01 21:15:01 +0100
+  Time.at(t, in: 'I')                 # => 2000-01-02 05:15:01 +0900
+  Time.at(t, in: 'K')                 # => 2000-01-02 06:15:01 +1000
+  Time.at(t, in: 'Y')                 # => 2000-01-01 08:15:01 -1200
+  Time.at(t, in: 'Z')                 # => 2000-01-01 20:15:01 UTC
+
+==== \Integer Offsets
+
+The zone value may be an integer number of seconds
+in the range <tt>-86399..86399</tt>:
+
+  t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC
+  Time.at(t, in: -86399)              # => 1999-12-31 20:15:02 -235959
+  Time.at(t, in: 86399)               # => 2000-01-02 20:15:00 +235959
+
+==== Timezone Objects
+
+In most cases, the zone value may be an object
+responding to certain timezone methods.
+
+\Exceptions (timezone object not allowed):
+
+- Time.new with positional argument +zone+.
+- Time.now with keyword argument +in:+.
+
+The timezone methods are:
+
+- +local_to_utc+:
+
+  - Called when Time.new is invoked with +tz+
+    as the value of positional argument +zone+ or keyword argument +in:+.
+  - Argument: a <tt>Time::tm</tt> object.
+  - Returns: a \Time-like object in the UTC timezone.
+
+- +utc_to_local+:
+
+  - Called when Time.at or Time.now is invoked with +tz+
+    as the value for keyword argument +in:+,
+    and when Time#getlocal or Time#localtime is called with +tz+
+    as the value for positional argument +zone+.
+  - Argument: a <tt>Time::tm</tt> object.
+  - Returns: a \Time-like object in the local timezone.
+
+A custom timezone class may have these instance methods,
+which will be called if defined:
+
+- +abbr+:
+
+  - Called when Time#strftime is invoked with a format involving <tt>%Z</tt>.
+  - Argument: a <tt>Time::tm</tt> object.
+  - Returns: a string abbreviation for the timezone name.
+
+- +dst?+:
+
+  - Called when Time.at or Time.now is invoked with +tz+
+    as the value for keyword argument +in:+,
+    and when Time#getlocal or Time#localtime is called with +tz+
+    as the value for positional argument +zone+.
+  - Argument: a <tt>Time::tm</tt> object.
+  - Returns: whether the time is daylight saving time.
+
+- +name+:
+
+  - Called when <tt>Marshal.dump(t) is invoked
+  - Argument: none.
+  - Returns: the string name of the timezone.

time.c

@@ -3852,7 +3852,7 @@ time_zonelocal(VALUE time, VALUE off)
  *    t.localtime("-09:00")               # => 2000-01-01 11:15:01 -0900
  *
  *  For forms of argument +zone+, see
- *  {Timezone Specifiers}[rdoc-ref:timezone_specifiers.rdoc].
+ *  {Timezone Specifiers}[rdoc-ref:timezones.rdoc].
  *
  */
 
@@ -3954,7 +3954,7 @@ time_fixoff(VALUE time)
  *    t.getlocal('+12:00')                  # => 2000-01-01 12:00:00 +1200
  *
  *  For forms of argument +zone+, see
- *  {Timezone Specifiers}[rdoc-ref:timezone_specifiers.rdoc].
+ *  {Timezone Specifiers}[rdoc-ref:timezones.rdoc].
  *
  */
 

timev.rb

@@ -208,38 +208,8 @@
 # - #ceil: Returns a new time with subseconds raised to a ceiling.
 # - #floor: Returns a new time with subseconds lowered to a floor.
 #
-# == Timezone Argument
+# For the forms of argument +zone+, see
-#
+# {Timezone Specifiers}[rdoc-ref:timezones.rdoc].
-# A timezone argument must have +local_to_utc+ and +utc_to_local+
-# methods, and may have +name+, +abbr+, and +dst?+ methods.
-#
-# The +local_to_utc+ method should convert a Time-like object from
-# the timezone to UTC, and +utc_to_local+ is the opposite.  The
-# result also should be a Time or Time-like object (not necessary to
-# be the same class).  The #zone of the result is just ignored.
-# Time-like argument to these methods is similar to a Time object in
-# UTC without subsecond; it has attribute readers for the parts,
-# e.g. #year, #month, and so on, and epoch time readers, #to_i.  The
-# subsecond attributes are fixed as 0, and #utc_offset, #zone,
-# #isdst, and their aliases are same as a Time object in UTC.
-# Also #to_time, #+, and #- methods are defined.
-#
-# The +name+ method is used for marshaling. If this method is not
-# defined on a timezone object, Time objects using that timezone
-# object can not be dumped by Marshal.
-#
-# The +abbr+ method is used by '%Z' in #strftime.
-#
-# The +dst?+ method is called with a +Time+ value and should return whether
-# the +Time+ value is in daylight savings time in the zone.
-#
-# === Auto Conversion to Timezone
-#
-# At loading marshaled data, a timezone name will be converted to a timezone
-# object by +find_timezone+ class method, if the method is defined.
-#
-# Similarly, that class method will be called when a timezone argument does
-# not have the necessary methods mentioned above.
 class Time
   # Creates a new \Time object from the current system time.
   # This is the same as Time.new without arguments.
@@ -248,7 +218,7 @@ class Time
   #    Time.now(in: '+04:00') # => 2009-06-24 07:39:54 +0400
   #
   # For forms of argument +zone+, see
-  # {Timezone Specifiers}[rdoc-ref:timezone_specifiers.rdoc].
+  # {Timezone Specifiers}[rdoc-ref:timezones.rdoc].
   def self.now(in: nil)
     Primitive.time_s_now(Primitive.arg!(:in))
   end
@@ -306,7 +276,7 @@ class Time
   #   Time.at(secs, in: '-12:00') # => 2000-12-31 17:59:59 -1200
   #
   # For the forms of argument +zone+, see
-  # {Timezone Specifiers}[rdoc-ref:timezone_specifiers.rdoc].
+  # {Timezone Specifiers}[rdoc-ref:timezones.rdoc].
   #
   def self.at(time, subsec = false, unit = :microsecond, in: nil)
     if Primitive.mandatory_only?
@@ -383,7 +353,7 @@ class Time
   # When positional argument +zone+ or keyword argument +in:+ is given,
   # the new \Time object is in the specified timezone.
   # For the forms of argument +zone+, see
-  # {Timezone Specifiers}[rdoc-ref:timezone_specifiers.rdoc]:
+  # {Timezone Specifiers}[rdoc-ref:timezones.rdoc]:
   #
   #   Time.new(2000, 1, 1, 0, 0, 0, '+12:00')
   #   # => 2000-01-01 00:00:00 +1200