Enhanced RDoc for Tim[DOC] (#6319)

1 files changed, 200 insertions, 158 deletions

diff --git a/time.c b/time.c
index 2b4323a536..a02e53d7f1 100644
--- a/time.c
+++ b/time.c
@@ -4160,13 +4160,16 @@ time_add(const struct time_object *tobj, VALUE torig, VALUE offset, int sign)
 
 /*
  *  call-seq:
- *     time + numeric -> time
+ *    self + numeric -> new_time
  *
- *  Adds some number of seconds (possibly including subsecond) to
- *  _time_ and returns that value as a new Time object.
+ *  Returns a new \Time object whose value is the sum of the numeric value
+ *  of +self+ and the given +numeric+:
  *
- *     t = Time.now         #=> 2020-07-20 22:14:43.170490982 +0900
- *     t + (60 * 60 * 24)   #=> 2020-07-21 22:14:43.170490982 +0900
+ *    t = Time.new(2000) # => 2000-01-01 00:00:00 -0600
+ *    t + (60 * 60 * 24) # => 2000-01-02 00:00:00 -0600
+ *    t + 0.5            # => 2000-01-01 00:00:00.5 -0600
+ *
+ *  Related: Time#-.
  */
 
 static VALUE
@@ -4183,17 +4186,24 @@ time_plus(VALUE time1, VALUE time2)
 
 /*
  *  call-seq:
- *     time - other_time -> float
- *     time - numeric    -> time
+ *    self - numeric -> new_time
+ *    self - other_time -> float
+ *
+ *  When +numeric+ is given,
+ *  returns a new \Time object whose value is the difference
+ *  of the numeric value of +self+ and +numeric+:
+ *
+ *    t = Time.new(2000) # => 2000-01-01 00:00:00 -0600
+ *    t - (60 * 60 * 24) # => 1999-12-31 00:00:00 -0600
+ *    t - 0.5            # => 1999-12-31 23:59:59.5 -0600
+ *
+ *  When +other_time+ is given,
+ *  returns a Float whose value is the difference
+ *  of the numeric values of +self+ and +other_time+:
  *
- *  Returns a difference in seconds as a Float
- *  between _time_ and +other_time+, or subtracts the given number
- *  of seconds in +numeric+ from _time_.
+ *    t - t # => 0.0
  *
- *     t = Time.now       #=> 2020-07-20 22:15:49.302766336 +0900
- *     t2 = t + 2592000   #=> 2020-08-19 22:15:49.302766336 +0900
- *     t2 - t             #=> 2592000.0
- *     t2 - 2592000       #=> 2020-07-20 22:15:49.302766336 +0900
+ *  Related: Time#+.
  */
 
 static VALUE
@@ -4228,31 +4238,30 @@ ndigits_denominator(VALUE ndigits)
 
 /*
  * call-seq:
- *   time.round([ndigits])   -> new_time
- *
- * Rounds subsecond to a given precision in decimal digits (0 digits by default).
- * It returns a new Time object.
- * +ndigits+ should be zero or a positive integer.
- *
- *     t = Time.utc(2010,3,30, 5,43,25.123456789r)
- *     t                       #=> 2010-03-30 05:43:25.123456789 UTC
- *     t.round                 #=> 2010-03-30 05:43:25 UTC
- *     t.round(0)              #=> 2010-03-30 05:43:25 UTC
- *     t.round(1)              #=> 2010-03-30 05:43:25.1 UTC
- *     t.round(2)              #=> 2010-03-30 05:43:25.12 UTC
- *     t.round(3)              #=> 2010-03-30 05:43:25.123 UTC
- *     t.round(4)              #=> 2010-03-30 05:43:25.1235 UTC
- *
- *     t = Time.utc(1999,12,31, 23,59,59)
- *     (t + 0.4).round         #=> 1999-12-31 23:59:59 UTC
- *     (t + 0.49).round        #=> 1999-12-31 23:59:59 UTC
- *     (t + 0.5).round         #=> 2000-01-01 00:00:00 UTC
- *     (t + 1.4).round         #=> 2000-01-01 00:00:00 UTC
- *     (t + 1.49).round        #=> 2000-01-01 00:00:00 UTC
- *     (t + 1.5).round         #=> 2000-01-01 00:00:01 UTC
- *
- *     t = Time.utc(1999,12,31, 23,59,59)     #=> 1999-12-31 23:59:59 UTC
- *     (t + 0.123456789).round(4).iso8601(6)  #=> 1999-12-31 23:59:59.1235 UTC
+ *   round(ndigits = 0) -> new_time
+ *
+ * Returns a new \Time object whose numeric value is that of +self+,
+ * with its seconds value rounded to precision +ndigits+:
+ *
+ *   t = Time.utc(2010, 3, 30, 5, 43, 25.123456789r)
+ *   t          # => 2010-03-30 05:43:25.123456789 UTC
+ *   t.round    # => 2010-03-30 05:43:25 UTC
+ *   t.round(0) # => 2010-03-30 05:43:25 UTC
+ *   t.round(1) # => 2010-03-30 05:43:25.1 UTC
+ *   t.round(2) # => 2010-03-30 05:43:25.12 UTC
+ *   t.round(3) # => 2010-03-30 05:43:25.123 UTC
+ *   t.round(4) # => 2010-03-30 05:43:25.1235 UTC
+ *
+ *   t = Time.utc(1999, 12,31, 23, 59, 59)
+ *   t                # => 1999-12-31 23:59:59 UTC
+ *   (t + 0.4).round  # => 1999-12-31 23:59:59 UTC
+ *   (t + 0.49).round # => 1999-12-31 23:59:59 UTC
+ *   (t + 0.5).round  # => 2000-01-01 00:00:00 UTC
+ *   (t + 1.4).round  # => 2000-01-01 00:00:00 UTC
+ *   (t + 1.49).round # => 2000-01-01 00:00:00 UTC
+ *   (t + 1.5).round  # => 2000-01-01 00:00:01 UTC
+ *
+ * Related: Time#ceil, Time#floor.
  */
 
 static VALUE
@@ -4278,29 +4287,29 @@ time_round(int argc, VALUE *argv, VALUE time)
 
 /*
  * call-seq:
- *   time.floor([ndigits])   -> new_time
- *
- * Floors subsecond to a given precision in decimal digits (0 digits by default).
- * It returns a new Time object.
- * +ndigits+ should be zero or a positive integer.
- *
- *     t = Time.utc(2010,3,30, 5,43,25.123456789r)
- *     t                       #=> 2010-03-30 05:43:25.123456789 UTC
- *     t.floor                 #=> 2010-03-30 05:43:25 UTC
- *     t.floor(0)              #=> 2010-03-30 05:43:25 UTC
- *     t.floor(1)              #=> 2010-03-30 05:43:25.1 UTC
- *     t.floor(2)              #=> 2010-03-30 05:43:25.12 UTC
- *     t.floor(3)              #=> 2010-03-30 05:43:25.123 UTC
- *     t.floor(4)              #=> 2010-03-30 05:43:25.1234 UTC
- *
- *     t = Time.utc(1999,12,31, 23,59,59)
- *     (t + 0.4).floor    #=> 1999-12-31 23:59:59 UTC
- *     (t + 0.9).floor    #=> 1999-12-31 23:59:59 UTC
- *     (t + 1.4).floor    #=> 2000-01-01 00:00:00 UTC
- *     (t + 1.9).floor    #=> 2000-01-01 00:00:00 UTC
- *
- *     t = Time.utc(1999,12,31, 23,59,59)
- *     (t + 0.123456789).floor(4)  #=> 1999-12-31 23:59:59.1234 UTC
+ *   floor(ndigits = 0) -> new_time
+ *
+ * Returns a new \Time object whose numerical value
+ * is less than or equal to +self+ with its seconds
+ * truncated to precision +ndigits+:
+ *
+ *   t = Time.utc(2010, 3, 30, 5, 43, 25.123456789r)
+ *   t           # => 2010-03-30 05:43:25.123456789 UTC
+ *   t.floor     # => 2010-03-30 05:43:25 UTC
+ *   t.floor(2)  # => 2010-03-30 05:43:25.12 UTC
+ *   t.floor(4)  # => 2010-03-30 05:43:25.1234 UTC
+ *   t.floor(6)  # => 2010-03-30 05:43:25.123456 UTC
+ *   t.floor(8)  # => 2010-03-30 05:43:25.12345678 UTC
+ *   t.floor(10) # => 2010-03-30 05:43:25.123456789 UTC
+ *
+ *   t = Time.utc(1999, 12, 31, 23, 59, 59)
+ *   t               # => 1999-12-31 23:59:59 UTC
+ *   (t + 0.4).floor # => 1999-12-31 23:59:59 UTC
+ *   (t + 0.9).floor # => 1999-12-31 23:59:59 UTC
+ *   (t + 1.4).floor # => 2000-01-01 00:00:00 UTC
+ *   (t + 1.9).floor # => 2000-01-01 00:00:00 UTC
+ *
+ * Related: Time#ceil, Time#round.
  */
 
 static VALUE
@@ -4323,29 +4332,29 @@ time_floor(int argc, VALUE *argv, VALUE time)
 
 /*
  * call-seq:
- *   time.ceil([ndigits])   -> new_time
- *
- * Ceils subsecond to a given precision in decimal digits (0 digits by default).
- * It returns a new Time object.
- * +ndigits+ should be zero or a positive integer.
- *
- *     t = Time.utc(2010,3,30, 5,43,25.0123456789r)
- *     t                      #=> 2010-03-30 05:43:25 123456789/10000000000 UTC
- *     t.ceil                 #=> 2010-03-30 05:43:26 UTC
- *     t.ceil(0)              #=> 2010-03-30 05:43:26 UTC
- *     t.ceil(1)              #=> 2010-03-30 05:43:25.1 UTC
- *     t.ceil(2)              #=> 2010-03-30 05:43:25.02 UTC
- *     t.ceil(3)              #=> 2010-03-30 05:43:25.013 UTC
- *     t.ceil(4)              #=> 2010-03-30 05:43:25.0124 UTC
- *
- *     t = Time.utc(1999,12,31, 23,59,59)
- *     (t + 0.4).ceil         #=> 2000-01-01 00:00:00 UTC
- *     (t + 0.9).ceil         #=> 2000-01-01 00:00:00 UTC
- *     (t + 1.4).ceil         #=> 2000-01-01 00:00:01 UTC
- *     (t + 1.9).ceil         #=> 2000-01-01 00:00:01 UTC
- *
- *     t = Time.utc(1999,12,31, 23,59,59)
- *     (t + 0.123456789).ceil(4)  #=> 1999-12-31 23:59:59.1235 UTC
+ *   ceil(ndigits = 0)   -> new_time
+ *
+ * Returns a new \Time object whose numerical value
+ * is greater than or equal to +self+ with its seconds
+ * truncated to precision +ndigits+:
+ *
+ *   t = Time.utc(2010, 3, 30, 5, 43, 25.123456789r)
+ *   t          # => 2010-03-30 05:43:25.123456789 UTC
+ *   t.ceil     # => 2010-03-30 05:43:26 UTC
+ *   t.ceil(2)  # => 2010-03-30 05:43:25.13 UTC
+ *   t.ceil(4)  # => 2010-03-30 05:43:25.1235 UTC
+ *   t.ceil(6)  # => 2010-03-30 05:43:25.123457 UTC
+ *   t.ceil(8)  # => 2010-03-30 05:43:25.12345679 UTC
+ *   t.ceil(10) # => 2010-03-30 05:43:25.123456789 UTC
+ *
+ *   t = Time.utc(1999, 12, 31, 23, 59, 59)
+ *   t              # => 1999-12-31 23:59:59 UTC
+ *   (t + 0.4).ceil # => 2000-01-01 00:00:00 UTC
+ *   (t + 0.9).ceil # => 2000-01-01 00:00:00 UTC
+ *   (t + 1.4).ceil # => 2000-01-01 00:00:01 UTC
+ *   (t + 1.9).ceil # => 2000-01-01 00:00:01 UTC
+ *
+ * Related: Time#floor, Time#round.
  */
 
 static VALUE
@@ -4371,16 +4380,19 @@ time_ceil(int argc, VALUE *argv, VALUE time)
 
 /*
  *  call-seq:
- *     time.sec -> integer
+ *    sec -> integer
  *
- *  Returns the second of the minute (0..60) for _time_.
+ *  Returns the integer second of the minute for +self+,
+ *  in range (0..60):
  *
- *  *Note:* Seconds range from zero to 60 to allow the system to inject
- *  leap seconds. See https://en.wikipedia.org/wiki/Leap_second for further
- *  details.
+ *    t = Time.new(2000, 1, 2, 3, 4, 5, 6)
+ *    # => 2000-01-02 03:04:05 +000006
+ *    t.sec # => 5
  *
- *     t = Time.now   #=> 2007-11-19 08:25:02 -0600
- *     t.sec          #=> 2
+ *  Note: the second value may be 60 when there is a
+ *  {leap second}[https://en.wikipedia.org/wiki/Leap_second].
+ *
+ *  Related: Time#year, Time#mon, Time#min.
  */
 
 static VALUE
@@ -4395,12 +4407,16 @@ time_sec(VALUE time)
 
 /*
  *  call-seq:
- *     time.min -> integer
+ *    min -> integer
+ *
+ *  Returns the integer minute of the hour for +self+,
+ *  in range (0..59):
  *
- *  Returns the minute of the hour (0..59) for _time_.
+ *    t = Time.new(2000, 1, 2, 3, 4, 5, 6)
+ *    # => 2000-01-02 03:04:05 +000006
+ *    t.min # => 4
  *
- *     t = Time.now   #=> 2007-11-19 08:25:51 -0600
- *     t.min          #=> 25
+ *  Related: Time#year, Time#mon, Time#sec.
  */
 
 static VALUE
@@ -4415,12 +4431,16 @@ time_min(VALUE time)
 
 /*
  *  call-seq:
- *     time.hour -> integer
+ *    hour -> integer
+ *
+ *  Returns the integer hour of the day for +self+,
+ *  in range (0..23):
  *
- *  Returns the hour of the day (0..23) for _time_.
+ *    t = Time.new(2000, 1, 2, 3, 4, 5, 6)
+ *    # => 2000-01-02 03:04:05 +000006
+ *    t.hour # => 3
  *
- *     t = Time.now   #=> 2007-11-19 08:26:20 -0600
- *     t.hour         #=> 8
+ *  Related: Time#year, Time#mon, Time#min.
  */
 
 static VALUE
@@ -4435,14 +4455,18 @@ time_hour(VALUE time)
 
 /*
  *  call-seq:
- *     time.day  -> integer
- *     time.mday -> integer
+ *    mday -> integer
  *
- *  Returns the day of the month (1..31) for _time_.
+ *  Returns the integer day of the month for +self+,
+ *  in range (1..31):
  *
- *     t = Time.now   #=> 2007-11-19 08:27:03 -0600
- *     t.day          #=> 19
- *     t.mday         #=> 19
+ *    t = Time.new(2000, 1, 2, 3, 4, 5, 6)
+ *    # => 2000-01-02 03:04:05 +000006
+ *    t.mday # => 2
+ *
+ *  Time#day is an alias for Time#mday.
+ *
+ *  Related: Time#year, Time#hour, Time#min.
  */
 
 static VALUE
@@ -4457,14 +4481,18 @@ time_mday(VALUE time)
 
 /*
  *  call-seq:
- *     time.mon   -> integer
- *     time.month -> integer
+ *    mon -> integer
+ *
+ *  Returns the integer month of the year for +self+,
+ *  in range (1..12):
  *
- *  Returns the month of the year (1..12) for _time_.
+ *    t = Time.new(2000, 1, 2, 3, 4, 5, 6)
+ *    # => 2000-01-02 03:04:05 +000006
+ *    t.mon # => 1
  *
- *     t = Time.now   #=> 2007-11-19 08:27:30 -0600
- *     t.mon          #=> 11
- *     t.month        #=> 11
+ *  Time#month is an alias for Time#mday.
+ *
+ *  Related: Time#year, Time#hour, Time#min.
  */
 
 static VALUE
@@ -4479,12 +4507,15 @@ time_mon(VALUE time)
 
 /*
  *  call-seq:
- *     time.year -> integer
+ *    year -> integer
+ *
+ *  Returns the integer year for +self+:
  *
- *  Returns the year for _time_ (including the century).
+ *    t = Time.new(2000, 1, 2, 3, 4, 5, 6)
+ *    # => 2000-01-02 03:04:05 +000006
+ *    t.year # => 2000
  *
- *     t = Time.now   #=> 2007-11-19 08:27:51 -0600
- *     t.year         #=> 2007
+ *  Related: Time#mon, Time#hour, Time#min.
  */
 
 static VALUE
@@ -4499,20 +4530,17 @@ time_year(VALUE time)
 
 /*
  *  call-seq:
- *     time.wday -> integer
- *
- *  Returns an integer representing the day of the week, 0..6, with
- *  Sunday == 0.
- *
- *     t = Time.now   #=> 2007-11-20 02:35:35 -0600
- *     t.wday         #=> 2
- *     t.sunday?      #=> false
- *     t.monday?      #=> false
- *     t.tuesday?     #=> true
- *     t.wednesday?   #=> false
- *     t.thursday?    #=> false
- *     t.friday?      #=> false
- *     t.saturday?    #=> false
+ *    wday -> integer
+ *
+ *  Returns the integer day of the week for +self+,
+ *  in range (0..6), with Sunday as zero.
+ *
+ *    t = Time.new(2000, 1, 2, 3, 4, 5, 6)
+ *    # => 2000-01-02 03:04:05 +000006
+ *    t.wday    # => 0
+ *    t.sunday? # => true
+ *
+ *  Related: Time#year, Time#hour, Time#min.
  */
 
 static VALUE
@@ -4531,12 +4559,14 @@ time_wday(VALUE time)
 
 /*
  *  call-seq:
- *     time.sunday? -> true or false
+ *    sunday? -> true or false
+ *
+ *  Returns +true+ if +self+ represents a Sunday, +false+ otherwise:
  *
- *  Returns +true+ if _time_ represents Sunday.
+ *    t = Time.utc(2000, 1, 2) # => 2000-01-02 00:00:00 UTC
+ *    t.sunday?                # => true
  *
- *     t = Time.local(1990, 4, 1)       #=> 1990-04-01 00:00:00 -0600
- *     t.sunday?                        #=> true
+ *  Related: Time#monday?, Time#tuesday?, Time#wednesday?.
  */
 
 static VALUE
@@ -4547,12 +4577,14 @@ time_sunday(VALUE time)
 
 /*
  *  call-seq:
- *     time.monday? -> true or false
+ *    monday? -> true or false
  *
- *  Returns +true+ if _time_ represents Monday.
+ *  Returns +true+ if +self+ represents a Monday, +false+ otherwise:
  *
- *     t = Time.local(2003, 8, 4)       #=> 2003-08-04 00:00:00 -0500
- *     t.monday?                        #=> true
+ *    t = Time.utc(2000, 1, 3) # => 2000-01-03 00:00:00 UTC
+ *    t.monday?                # => true
+ *
+ *  Related: Time#tuesday?, Time#wednesday?, Time#thursday?.
  */
 
 static VALUE
@@ -4563,12 +4595,14 @@ time_monday(VALUE time)
 
 /*
  *  call-seq:
- *     time.tuesday? -> true or false
+ *    tuesday? -> true or false
+ *
+ *  Returns +true+ if +self+ represents a Tuesday, +false+ otherwise:
  *
- *  Returns +true+ if _time_ represents Tuesday.
+ *    t = Time.utc(2000, 1, 4) # => 2000-01-04 00:00:00 UTC
+ *    t.tuesday?               # => true
  *
- *     t = Time.local(1991, 2, 19)      #=> 1991-02-19 00:00:00 -0600
- *     t.tuesday?                       #=> true
+ *  Related: Time#wednesday?, Time#thursday?, Time#friday?.
  */
 
 static VALUE
@@ -4579,12 +4613,14 @@ time_tuesday(VALUE time)
 
 /*
  *  call-seq:
- *     time.wednesday? -> true or false
+ *    wednesday? -> true or false
+ *
+ *  Returns +true+ if +self+ represents a Wednesday, +false+ otherwise:
  *
- *  Returns +true+ if _time_ represents Wednesday.
+ *    t = Time.utc(2000, 1, 5) # => 2000-01-05 00:00:00 UTC
+ *    t.wednesday?             # => true
  *
- *     t = Time.local(1993, 2, 24)      #=> 1993-02-24 00:00:00 -0600
- *     t.wednesday?                     #=> true
+ *  Related: Time#thursday?, Time#friday?, Time#saturday?.
  */
 
 static VALUE
@@ -4595,12 +4631,14 @@ time_wednesday(VALUE time)
 
 /*
  *  call-seq:
- *     time.thursday? -> true or false
+ *    thursday? -> true or false
  *
- *  Returns +true+ if _time_ represents Thursday.
+ *  Returns +true+ if +self+ represents a Thursday, +false+ otherwise:
  *
- *     t = Time.local(1995, 12, 21)     #=> 1995-12-21 00:00:00 -0600
- *     t.thursday?                      #=> true
+ *    t = Time.utc(2000, 1, 6) # => 2000-01-06 00:00:00 UTC
+ *    t.thursday?              # => true
+ *
+ *  Related: Time#friday?, Time#saturday?, Time#sunday?.
  */
 
 static VALUE
@@ -4611,12 +4649,14 @@ time_thursday(VALUE time)
 
 /*
  *  call-seq:
- *     time.friday? -> true or false
+ *    friday? -> true or false
+ *
+ *  Returns +true+ if +self+ represents a Friday, +false+ otherwise:
  *
- *  Returns +true+ if _time_ represents Friday.
+ *    t = Time.utc(2000, 1, 7) # => 2000-01-07 00:00:00 UTC
+ *    t.friday?                # => true
  *
- *     t = Time.local(1987, 12, 18)     #=> 1987-12-18 00:00:00 -0600
- *     t.friday?                        #=> true
+ *  Related: Time#saturday?, Time#sunday?, Time#monday?.
  */
 
 static VALUE
@@ -4627,12 +4667,14 @@ time_friday(VALUE time)
 
 /*
  *  call-seq:
- *     time.saturday? -> true or false
+ *    saturday? -> true or false
+ *
+ *  Returns +true+ if +self+ represents a Saturday, +false+ otherwise:
  *
- *  Returns +true+ if _time_ represents Saturday.
+ *    t = Time.utc(2000, 1, 1) # => 2000-01-01 00:00:00 UTC
+ *    t.saturday?              # => true
  *
- *     t = Time.local(2006, 6, 10)      #=> 2006-06-10 00:00:00 -0500
- *     t.saturday?                      #=> true
+ *  Related: Time#sunday?, Time#monday?, Time#tuesday?.
  */
 
 static VALUE