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 @@
-- in: zone: a timezone _zone_, which may be:
- - A string offset from UTC.
- - A single letter offset from UTC, in the range 'A'..'Z',
- 'J' excluded (the so-called military timezone).
- - An integer number of seconds.
- - A timezone object;
- see {Timezone Argument}[#class-Time-label-Timezone+Argument] for details.
+- in: zone: 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 'A'..'Z',
- 'J' excluded (the so-called military timezone).
- - An integer number of seconds.
- - A timezone object;
- see {Timezone Argument}[#class-Time-label-Timezone+Argument] for details.
-- in: zone: a timezone _zone_, which may be as above.
+- +zone+: a timezone +zone+.
+- in: zone: 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 '+HH:MM' or -HH:MM,
+ where:
+
+ - +HH+ is the 2-digit hour in the range 0..23.
+ - +MM+ is the 2-digit minute in the range 0..59.
+
+ 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 'A'..'I' or 'K'..'Z';
+ 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 -86399..86399:
+
+ 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.
diff --git a/time.c b/time.c
index a7a4c5dc1a..e0cb7537ec 100644
--- 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
diff --git a/timev.rb b/timev.rb
index a7e70b290f..1fd8295d0f 100644
--- 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