[DOC] Enhanced RDoc for Time (#6294)

Merged-By: BurdetteLamar <BurdetteLamar@Yahoo.com>

time.c

@@ -3487,18 +3487,18 @@ time_s_mktime(int argc, VALUE *argv, VALUE klass)
  *  call-seq:
  *    to_i -> integer
  *
- *  Returns the number of seconds since the Epoch
- *  for the time represented in +self+:
+ *  Returns the value of +self+ as integer
+ *  {Epoch seconds}[rdoc-ref:Time@Epoch+Seconds];
+ *  subseconds are truncated (not rounded):
  *
- *    Time.utc(1970, 1, 1).to_i # => 0
- *    t = Time.now.to_i         # => 1595263289
- *
- *  Subseconds are omitted:
- *
- *    t = Time.now # => 2022-07-12 09:13:48.5075976 -0500
- *    t.to_i       # => 1657635228
+ *    Time.utc(1970, 1, 1, 0, 0, 0).to_i         # => 0
+ *    Time.utc(1970, 1, 1, 0, 0, 0, 999999).to_i # => 0
+ *    Time.utc(1950, 1, 1, 0, 0, 0).to_i         # => -631152000
+ *    Time.utc(1990, 1, 1, 0, 0, 0).to_i         # => 631152000
  *
  *  Time#tv_sec is an alias for Time#to_i.
+ *
+ *  Related: Time#to_f Time#to_r.
  */
 
 static VALUE
@@ -3514,16 +3514,20 @@ time_to_i(VALUE time)
  *  call-seq:
  *    to_f -> float
  *
- *  Returns the value of +self+ as a Float number of seconds
- *  since the Epoch.
+ *  Returns the value of +self+ as a Float number
+ *  {Epoch seconds}[rdoc-ref:Time@Epoch+Seconds];
+ *  subseconds are included.
+ *
  *  The stored value of +self+ is a
  *  {Rational}[rdoc-ref:Rational@#method-i-to_f],
  *  which means that the returned value may be approximate:
  *
- *    t = Time.now # => 2022-07-07 11:23:18.0784889 -0500
- *    t.to_f       # => 1657210998.0784888
- *    t.to_i       # => 1657210998
+ *    Time.utc(1970, 1, 1, 0, 0, 0).to_f         # => 0.0
+ *    Time.utc(1970, 1, 1, 0, 0, 0, 999999).to_f # => 0.999999
+ *    Time.utc(1950, 1, 1, 0, 0, 0).to_f         # => -631152000.0
+ *    Time.utc(1990, 1, 1, 0, 0, 0).to_f         # => 631152000.0
  *
+ *  Related: Time#to_i, Time#to_r.
  */
 
 static VALUE
@@ -3539,11 +3543,12 @@ time_to_f(VALUE time)
  *  call-seq:
  *    to_r -> rational
  *
- *  Returns the value of +self+ as a Rational number of seconds
- *  since the Epoch, which is exact:
+ *  Returns the value of +self+ as a Rational exact number of
+ *  {Epoch seconds}[rdoc-ref:Time@Epoch+Seconds];
  *
  *    Time.now.to_r # => (16571402750320203/10000000)
  *
+ *  Related: Time#to_f, Time#to_i.
  */
 
 static VALUE

timev.rb

@@ -1,19 +1,49 @@
-# Time is an abstraction of dates and times. Time is stored internally as
-# the number of seconds with subsecond since the _Epoch_,
-# 1970-01-01 00:00:00 UTC.
+# A \Time object represents a date and time:
 #
-# The Time class treats GMT
-# (Greenwich Mean Time) and UTC (Coordinated Universal Time) as equivalent.
-# GMT is the older way of referring to these baseline times but persists in
-# the names of calls on POSIX systems.
+#   Time.new(2000, 1, 1, 0, 0, 0) # => 2000-01-01 00:00:00 -0600
 #
-# Note: A \Time object uses the resolution available on your system clock.
+# Although its value can be expressed as a single numeric
+# (see {Epoch Seconds}[rdoc-ref:Time@Epoch+Seconds] below),
+# it can be convenient to deal with the value by parts:
 #
-# All times may have subsecond. Be aware of this fact when comparing times
-# with each other -- times that are apparently equal when displayed may be
-# different when compared.
-# (Since Ruby 2.7.0, Time#inspect shows subsecond but
-# Time#to_s still doesn't show subsecond.)
+#   t = Time.new(-2000, 1, 1, 0, 0, 0.0)
+#   # => -2000-01-01 00:00:00 -0600
+#   t.year # => -2000
+#   t.month # => 1
+#   t.mday # => 1
+#   t.hour # => 0
+#   t.min # => 0
+#   t.sec # => 0
+#   t.subsec # => 0
+#
+#   t = Time.new(2000, 12, 31, 23, 59, 59.5)
+#   # => 2000-12-31 23:59:59.5 -0600
+#   t.year # => 2000
+#   t.month # => 12
+#   t.mday # => 31
+#   t.hour # => 23
+#   t.min # => 59
+#   t.sec # => 59
+#   t.subsec # => (1/2)
+#
+# == Epoch Seconds
+#
+<i>Epoch seconds</i> is the exact number of seconds
+(including fractional subseconds) since the Unix Epoch, January 1, 1970.
+#
+# You can retrieve that value exactly using method Time.to_r:
+#
+#   Time.at(0).to_r        # => (0/1)
+#   Time.at(0.999999).to_r # => (9007190247541737/9007199254740992)
+#
+# Other retrieval methods such as Time#to_i and Time#to_f
+# may return a value that rounds or truncates subseconds.
+#
+# == \Time Resolution
+#
+# A \Time object derived from the system clock
+# (for example, by method Time.now)
+# has the resolution supported by the system.
 #
 # == Examples
 #
@@ -229,7 +259,9 @@ class Time
   #
   # - A \Time object, whose value is the basis for the returned time;
   #   also influenced by optional keyword argument +in:+ (see below).
-  # - A numeric number of seconds (since the epoch) for the returned time.
+  # - A numeric number of
+  #   {Epoch seconds}[rdoc-ref:Time@Epoch+Seconds]
+  #   for the returned time.
   #
   # Examples:
   #
@@ -259,7 +291,7 @@ class Time
   #     Time.at(secs, 1000000, :microsecond)  # => 2001-01-01 00:00:00 -0600
   #     Time.at(secs, -1000000, :microsecond) # => 2000-12-31 23:59:58 -0600
   #
-  # - +:nsec+ or +:nanosecond+: +subsec+ in nanoseconds:
+  # - +:nanosecond+ or +:nsec+: +subsec+ in nanoseconds:
   #
   #     Time.at(secs, 0, :nanosecond)           # => 2000-12-31 23:59:59 -0600
   #     Time.at(secs, 500000000, :nanosecond)   # => 2000-12-31 23:59:59.5 -0600