[DOC] Enhanced RDoc for Time (#6255)

Treats: #utc #hash #localtime
2022-08-21 11:36:36 -05:00 · 2022-08-21 11:36:36 -05:00 · 936327a519
--- 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].
--- 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].
--- a/doc/timezone_specifiers.rdoc
+++ 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.
--- a/time.c
+++ b/time.c
@ -3486,7 +3486,7 @@ time_to_f(VALUE time)

 /*
 *  call-seq:
- *    time.to_r -> rational
+ *    to_r -> rational
 *
 *  Returns the value of +self+ as a Rational number of seconds
 *  since the Epoch, which is exact:
@ -3540,7 +3540,7 @@ time_usec(VALUE time)

 /*
 *  call-seq:
- *    time.nsec -> integer
+ *    nsec -> integer
 *
 *  Returns the number of nanoseconds in the subseconds part of +self+
 *  in the range (0..999_999_999);
@ -3659,20 +3659,20 @@ time_eql(VALUE time1, VALUE time2)

 /*
 *  call-seq:
- *     time.utc? -> true or false
- *     time.gmt? -> true or false
+ *    utc? -> true or false
 *
- *  Returns +true+ if _time_ represents a time in UTC (GMT).
+ *  Returns +true+ if +self+ represents a time in UTC (GMT):
 *
- *     t = Time.now                        #=> 2007-11-19 08:15:23 -0600
- *     t.utc?                              #=> false
- *     t = Time.gm(2000,"jan",1,20,15,1)   #=> 2000-01-01 20:15:01 UTC
- *     t.utc?                              #=> true
+ *    now = Time.now
+ *    # => 2022-08-18 10:24:13.5398485 -0500
+ *    now.utc? # => false
+ *    utc = Time.utc(2000, 1, 1, 20, 15, 1)
+ *    # => 2000-01-01 20:15:01 UTC
+ *    utc.utc? # => true
 *
- *     t = Time.now                        #=> 2007-11-19 08:16:03 -0600
- *     t.gmt?                              #=> false
- *     t = Time.gm(2000,1,1,20,15,1)       #=> 2000-01-01 20:15:01 UTC
- *     t.gmt?                              #=> true
+ *  Time#gmt? is an alias for Time#utc?.
+ *
+ *  Related: Time.utc.
 */

 static VALUE
@ -3686,11 +3686,11 @@ time_utc_p(VALUE time)

 /*
 * call-seq:
- *   time.hash   -> integer
+ *   hash -> integer
 *
- * Returns a hash code for this Time object.
+ * Returns the integer hash code for +self+.
 *
- * See also Object#hash.
+ * Related: Object#hash.
 */

 static VALUE
@ -3777,25 +3777,27 @@ time_zonelocal(VALUE time, VALUE off)

 /*
 *  call-seq:
- *     time.localtime -> time
- *     time.localtime(utc_offset) -> time
+ *    localtime -> self or new_time
+ *    localtime(zone) -> new_time
 *
- *  Converts _time_ to local time (using the local time zone in
- *  effect at the creation time of _time_) modifying the receiver.
+ *  With no argument given:
 *
- *  If +utc_offset+ is given, it is used instead of the local time.
+ *  - Returns +self+ if +self+ is a local time.
+ *  - Otherwise returns a new \Time in the user's local timezone:
 *
- *     t = Time.utc(2000, "jan", 1, 20, 15, 1) #=> 2000-01-01 20:15:01 UTC
- *     t.utc?                                  #=> true
+ *      t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC
+ *      t.localtime                         # => 2000-01-01 14:15:01 -0600
 *
- *     t.localtime                             #=> 2000-01-01 14:15:01 -0600
- *     t.utc?                                  #=> false
+ *  With argument +zone+ given,
+ *  returns the new \Time object created by converting
+ *  +self+ to the given time zone:
 *
- *     t.localtime("+09:00")                   #=> 2000-01-02 05:15:01 +0900
- *     t.utc?                                  #=> false
+ *    t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC
+ *    t.localtime("-09:00")               # => 2000-01-01 11:15:01 -0900
+ *
+ *  For forms of argument +zone+, see
+ *  {Timezone Specifiers}[rdoc-ref:doc/timezone_specifiers.rdoc].
 *
- *  If +utc_offset+ is not given and _time_ is local time, just returns
- *  the receiver.
 */

 static VALUE
--- a/timev.rb
+++ b/timev.rb
@ -217,8 +217,8 @@ class Time
  #    Time.now               # => 2009-06-24 12:39:54 +0900
  #    Time.now(in: '+04:00') # => 2009-06-24 07:39:54 +0400
  #
-  # Parameter:
-  # :include: doc/time/in.rdoc
+  # For forms of argument +zone+, see
+  # {Timezone Specifiers}[rdoc-ref:doc/timezone_specifiers.rdoc].
  def self.now(in: nil)
    Primitive.time_s_now(Primitive.arg!(:in))
  end