[DOC] Enhanced RDoc for Time (#6308)

More on timezones.

1 files changed, 108 insertions, 0 deletions

diff --git a/doc/timezones.rdoc b/doc/timezones.rdoc
new file mode 100644
index 0000000000..c3aae88fde
--- /dev/null
+++ b/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.