[DOC] Enhanced RDoc for Time (#6255)

Treats:
    #utc
    #hash
    #localtime

3 files changed, 54 insertions, 15 deletions

diff --git a/doc/time/in.rdoc b/doc/time/in.rdoc
index 870982b0c2..33178c514a 100644
--- a/doc/time/in.rdoc
+++ b/doc/time/in.rdoc
@@ -1,7 +1,4 @@
-- <tt>in: zone</tt>: a timezone _zone_, which may be:
-  - A string offset from UTC.
-  - A single letter offset from UTC, in the range <tt>'A'..'Z'</tt>,
-    <tt>'J'</tt> excluded (the so-called military timezone).
-  - An integer number of seconds.
-  - A timezone object;
-    see {Timezone Argument}[#class-Time-label-Timezone+Argument] for details.
+- <tt>in: zone</tt>: a timezone +zone+.
+
+For forms of argument +zone+, see
+{Timezone Specifiers}[rdoc-ref:doc/timezone_specifiers.rdoc].
diff --git a/doc/time/zone_and_in.rdoc b/doc/time/zone_and_in.rdoc
index 5bdfaacd4c..2cf6564c01 100644
--- a/doc/time/zone_and_in.rdoc
+++ b/doc/time/zone_and_in.rdoc
@@ -1,8 +1,5 @@
-- +zone+: a timezone, which may be:
-  - A string offset from UTC.
-  - A single letter offset from UTC, in the range <tt>'A'..'Z'</tt>,
-    <tt>'J'</tt> excluded (the so-called military timezone).
-  - An integer number of seconds.
-  - A timezone object;
-    see {Timezone Argument}[#class-Time-label-Timezone+Argument] for details.
-- <tt>in: zone</tt>: a timezone _zone_, which may be as above.
+- +zone+: a timezone +zone+.
+- <tt>in: zone</tt>: a timezone +zone+.
+
+For forms of +zone+, see
+{Timezone Specifiers}[rdoc-ref:doc/timezone_specifiers.rdoc].
diff --git a/doc/timezone_specifiers.rdoc b/doc/timezone_specifiers.rdoc
new file mode 100644
index 0000000000..f1c23372b1
--- /dev/null
+++ b/doc/timezone_specifiers.rdoc
@@ -0,0 +1,45 @@
+=== 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#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.