rbs 3.3.2 → 3.4.0.pre.1

data/core/time.rbs

@@ -1,5 +1,5 @@
 # <!-- rdoc-file=timev.rb -->
-# A Time object represents a date and time:
+# A `Time` object represents a date and time:
 #
 #     Time.new(2000, 1, 1, 0, 0, 0) # => 2000-01-01 00:00:00 -0600
 #
@@ -42,14 +42,14 @@
 #
 # ## Time Resolution
 #
-# A Time object derived from the system clock (for example, by method Time.now)
-# has the resolution supported by the system.
+# A `Time` object derived from the system clock (for example, by method
+# Time.now) has the resolution supported by the system.
 #
 # ## Examples
 #
 # All of these examples were done using the EST timezone which is GMT-5.
 #
-# ### Creating a New Time Instance
+# ### Creating a New `Time` Instance
 #
 # You can create a new instance of Time with Time.new. This will use the current
 # system time. Time.now is an alias for this. You can also pass parts of the
@@ -66,7 +66,7 @@
 #
 #     Time.new(2002, 10, 31, 2, 2, 2, "+02:00") #=> 2002-10-31 02:02:02 +0200
 #
-# Or a timezone object:
+# Or [a timezone object](rdoc-ref:Time@Timezone+Objects):
 #
 #     zone = timezone("Europe/Athens")      # Eastern European Time, UTC+2
 #     Time.new(2002, 10, 31, 2, 2, 2, zone) #=> 2002-10-31 02:02:02 +0200
@@ -80,7 +80,7 @@
 #
 #     Time.at(628232400) #=> 1989-11-28 00:00:00 -0500
 #
-# ### Working with an Instance of Time
+# ### Working with an Instance of `Time`
 #
 # Once you have an instance of Time there is a multitude of things you can do
 # with it. Below are some examples. For all of the following examples, we will
@@ -122,20 +122,20 @@
 #
 # ## What's Here
 #
-# First, what's elsewhere. Class Time:
+# First, what's elsewhere. Class `Time`:
 #
 # *   Inherits from [class Object](rdoc-ref:Object@What-27s+Here).
 # *   Includes [module Comparable](rdoc-ref:Comparable@What-27s+Here).
 #
 #
-# Here, class Time provides methods that are useful for:
+# Here, class `Time` provides methods that are useful for:
 #
-# *   [Creating \Time objects](rdoc-ref:Time@Methods+for+Creating).
-# *   [Fetching \Time values](rdoc-ref:Time@Methods+for+Fetching).
-# *   [Querying a \Time object](rdoc-ref:Time@Methods+for+Querying).
-# *   [Comparing \Time objects](rdoc-ref:Time@Methods+for+Comparing).
-# *   [Converting a \Time object](rdoc-ref:Time@Methods+for+Converting).
-# *   [Rounding a \Time](rdoc-ref:Time@Methods+for+Rounding).
+# *   {Creating `Time`[objects}](rdoc-ref:Time@Methods+for+Creating).
+# *   {Fetching `Time`[values}](rdoc-ref:Time@Methods+for+Fetching).
+# *   {Querying a `Time`[object}](rdoc-ref:Time@Methods+for+Querying).
+# *   {Comparing `Time`[objects}](rdoc-ref:Time@Methods+for+Comparing).
+# *   {Converting a `Time`[object}](rdoc-ref:Time@Methods+for+Converting).
+# *   {Rounding a `Time`[}](rdoc-ref:Time@Methods+for+Rounding).
 #
 #
 # ### Methods for Creating
@@ -219,7 +219,174 @@
 #
 #
 # For the forms of argument `zone`, see [Timezone
-# Specifiers](rdoc-ref:timezones.rdoc).
+# Specifiers](rdoc-ref:Time@Timezone+Specifiers).
+#
+# ## Timezone Specifiers
+#
+# Certain `Time` methods 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#getlocal: positional argument `zone`.
+# *   Time#localtime: positional argument `zone`.
+#
+#
+# The value given with any of these must be one of the following (each detailed
+# below):
+#
+# *   [Hours/minutes offset](rdoc-ref:Time@Hours-2FMinutes+Offsets).
+# *   [Single-letter offset](rdoc-ref:Time@Single-Letter+Offsets).
+# *   [Integer offset](rdoc-ref:Time@Integer+Offsets).
+# *   [Timezone object](rdoc-ref:Time@Timezone+Objects).
+# *   [Timezone name](rdoc-ref:Time@Timezone+Names).
+#
+#
+# ### Hours/Minutes Offsets
+#
+# The zone value may be 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
+#
+# ### Single-Letter Offsets
+#
+# The zone value may be 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
+#
+# ### Integer Offsets
+#
+# The zone value may be 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
+#
+# ### Timezone Objects
+#
+# The zone value may be an object responding to certain timezone methods, an
+# instance of [Timezone](https://github.com/panthomakos/timezone) and
+# [TZInfo](https://tzinfo.github.io) for example.
+#
+# The timezone methods are:
+#
+# *   `local_to_utc`:
+#
+#     *   Called when Time.new is invoked with `tz` as the value of positional
+#         argument `zone` or keyword argument `in:`.
+#     *   Argument: a [Time-like object](rdoc-ref:Time@Time-Like+Objects).
+#     *   Returns: a [Time-like object](rdoc-ref:Time@Time-Like+Objects) in the
+#         UTC timezone.
+#
+#
+# *   `utc_to_local`:
+#
+#     *   Called when Time.at or Time.now is invoked with `tz` as the value for
+#         keyword argument `in:`, and when Time#getlocal or Time#localtime is
+#         called with `tz` as the value for positional argument `zone`.
+#     *   Argument: a [Time-like object](rdoc-ref:Time@Time-Like+Objects).
+#     *   Returns: a [Time-like object](rdoc-ref:Time@Time-Like+Objects) in the
+#         local timezone.
+#
+#
+#
+# A custom timezone class may have these instance methods, which will be called
+# if defined:
+#
+# *   `abbr`:
+#
+#     *   Called when Time#strftime is invoked with a format involving `%Z`.
+#     *   Argument: a [Time-like object](rdoc-ref:Time@Time-Like+Objects).
+#     *   Returns: a string abbreviation for the timezone name.
+#
+#
+# *   `dst?`:
+#
+#     *   Called when Time.at or Time.now is invoked with `tz` as the value for
+#         keyword argument `in:`, and when Time#getlocal or Time#localtime is
+#         called with `tz` as the value for positional argument `zone`.
+#     *   Argument: a [Time-like object](rdoc-ref:Time@Time-Like+Objects).
+#     *   Returns: whether the time is daylight saving time.
+#
+#
+# *   `name`:
+#
+#     *   Called when `Marshal.dump(t)` is invoked
+#     *   Argument: none.
+#     *   Returns: the string name of the timezone.
+#
+#
+#
+# #### `Time`-Like Objects
+#
+# A `Time`-like object is a container object capable of interfacing with
+# timezone libraries for timezone conversion.
+#
+# The argument to the timezone conversion methods above will have attributes
+# similar to Time, except that timezone related attributes are meaningless.
+#
+# The objects returned by `local_to_utc` and `utc_to_local` methods of the
+# timezone object may be of the same class as their arguments, of arbitrary
+# object classes, or of class Integer.
+#
+# For a returned class other than `Integer`, the class must have the following
+# methods:
+#
+# *   `year`
+# *   `mon`
+# *   `mday`
+# *   `hour`
+# *   `min`
+# *   `sec`
+# *   `isdst`
+# *   `to_i`
+#
+#
+# For a returned `Integer`, its components, decomposed in UTC, are interpreted
+# as times in the specified timezone.
+#
+# ### Timezone Names
+#
+# If the class (the receiver of class methods, or the class of the receiver of
+# instance methods) has `find_timezone` singleton method, this method is called
+# to achieve the corresponding timezone object from a timezone name.
+#
+# For example, using [Timezone](https://github.com/panthomakos/timezone):
+#     class TimeWithTimezone < Time
+#       require 'timezone'
+#       def self.find_timezone(z) = Timezone[z]
+#     end
+#
+#     TimeWithTimezone.now(in: "America/New_York")        #=> 2023-12-25 00:00:00 -0500
+#     TimeWithTimezone.new("2023-12-25 America/New_York") #=> 2023-12-25 00:00:00 -0500
+#
+# Or, using [TZInfo](https://tzinfo.github.io):
+#     class TimeWithTZInfo < Time
+#       require 'tzinfo'
+#       def self.find_timezone(z) = TZInfo::Timezone.get(z)
+#     end
+#
+#     TimeWithTZInfo.now(in: "America/New_York")          #=> 2023-12-25 00:00:00 -0500
+#     TimeWithTZInfo.new("2023-12-25 America/New_York")   #=> 2023-12-25 00:00:00 -0500
+#
+# You can define this method per subclasses, or on the toplevel Time class.
 #
 class Time < Object
   include Comparable
@@ -228,11 +395,11 @@ class Time < Object
   #   rdoc-file=timev.rb
   #   - at(time, subsec = false, unit = :microsecond, in: nil)
   # -->
-  # Returns a new Time object based on the given arguments.
+  # Returns a new `Time` object based on the given arguments.
   #
   # Required argument `time` may be either of:
   #
-  # *   A Time object, whose value is the basis for the returned time; also
+  # *   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 [Epoch seconds](rdoc-ref:Time@Epoch+Seconds) for the
   #     returned time.
@@ -274,14 +441,14 @@ class Time < Object
   #         Time.at(secs, -1000000000, :nanosecond) # => 2000-12-31 23:59:58 -0600
   #
   #
-  # Optional keyword argument `+in: zone` specifies the timezone for the returned
+  # Optional keyword argument `in: zone` specifies the timezone for the returned
   # time:
   #
   #     Time.at(secs, in: '+12:00') # => 2001-01-01 17:59:59 +1200
   #     Time.at(secs, in: '-12:00') # => 2000-12-31 17:59:59 -1200
   #
   # For the forms of argument `zone`, see [Timezone
-  # Specifiers](rdoc-ref:timezones.rdoc).
+  # Specifiers](rdoc-ref:Time@Timezone+Specifiers).
   #
   def self.at: (Time, ?in: String | Integer | nil) -> Time
              | (Numeric, ?in: String | Integer | nil) -> Time
@@ -290,7 +457,7 @@ class Time < Object
   type subsec_unit = :msec | :millisecond | :usec | :microsecond | :nsec | :nanosecond
 
   # <!-- rdoc-file=time.c -->
-  # Returns a new Time object based the on given arguments, in the UTC timezone.
+  # Returns a new `Time` object based the on given arguments, in the UTC timezone.
   #
   # With one to seven arguments given, the arguments are interpreted as in the
   # first calling sequence above:
@@ -367,7 +534,7 @@ class Time < Object
   #     # => [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
   #     Time.utc(*a) # => 0005-04-03 02:01:00 UTC
   #
-  # This form is useful for creating a Time object from a 10-element array
+  # This form is useful for creating a `Time` object from a 10-element array
   # returned by Time.to_a:
   #
   #     t = Time.new(2000, 1, 2, 3, 4, 5, 6) # => 2000-01-02 03:04:05 +000006
@@ -381,8 +548,6 @@ class Time < Object
   # Raises an exception if the number of arguments is eight, nine, or greater than
   # ten.
   #
-  # Time.gm is an alias for Time.utc.
-  #
   # Related: Time.local.
   #
   def self.gm: (Integer year, ?Integer | String month, ?Integer day, ?Integer hour, ?Integer min, ?Numeric sec, ?Numeric usec_with_frac) -> Time
@@ -392,7 +557,7 @@ class Time < Object
   #   - Time.local(year, month = 1, mday = 1, hour = 0, min = 0, sec = 0, usec = 0) -> new_time
   #   - Time.local(sec, min, hour, mday, month, year, dummy, dummy, dummy, dummy) -> new_time
   # -->
-  # Like Time.utc, except that the returned Time object has the local timezone,
+  # Like Time.utc, except that the returned `Time` object has the local timezone,
   # not the UTC timezone:
   #
   #     # With seven arguments.
@@ -408,14 +573,14 @@ class Time < Object
   #   rdoc-file=timev.rb
   #   - now(in: nil)
   # -->
-  # Creates a new Time object from the current system time. This is the same as
+  # Creates a new `Time` object from the current system time. This is the same as
   # Time.new without arguments.
   #
   #     Time.now               # => 2009-06-24 12:39:54 +0900
   #     Time.now(in: '+04:00') # => 2009-06-24 07:39:54 +0400
   #
   # For forms of argument `zone`, see [Timezone
-  # Specifiers](rdoc-ref:timezones.rdoc).
+  # Specifiers](rdoc-ref:Time@Timezone+Specifiers).
   #
   def self.now: (?in: String | Integer | nil) -> Time
 
@@ -424,7 +589,7 @@ class Time < Object
   #   - Time.utc(year, month = 1, mday = 1, hour = 0, min = 0, sec = 0, usec = 0) -> new_time
   #   - Time.utc(sec, min, hour, mday, month, year, dummy, dummy, dummy, dummy) -> new_time
   # -->
-  # Returns a new Time object based the on given arguments, in the UTC timezone.
+  # Returns a new `Time` object based the on given arguments, in the UTC timezone.
   #
   # With one to seven arguments given, the arguments are interpreted as in the
   # first calling sequence above:
@@ -501,7 +666,7 @@ class Time < Object
   #     # => [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
   #     Time.utc(*a) # => 0005-04-03 02:01:00 UTC
   #
-  # This form is useful for creating a Time object from a 10-element array
+  # This form is useful for creating a `Time` object from a 10-element array
   # returned by Time.to_a:
   #
   #     t = Time.new(2000, 1, 2, 3, 4, 5, 6) # => 2000-01-02 03:04:05 +000006
@@ -515,8 +680,6 @@ class Time < Object
   # Raises an exception if the number of arguments is eight, nine, or greater than
   # ten.
   #
-  # Time.gm is an alias for Time.utc.
-  #
   # Related: Time.local.
   #
   def self.utc: (Integer year, ?Integer | String month, ?Integer day, ?Integer hour, ?Integer min, ?Numeric sec, ?Numeric usec_with_frac) -> Time
@@ -525,7 +688,7 @@ class Time < Object
   #   rdoc-file=time.c
   #   - self + numeric -> new_time
   # -->
-  # Returns a new Time object whose value is the sum of the numeric value of
+  # Returns a new `Time` object whose value is the sum of the numeric value of
   # `self` and the given `numeric`:
   #
   #     t = Time.new(2000) # => 2000-01-01 00:00:00 -0600
@@ -541,7 +704,7 @@ class Time < Object
   #   - self - numeric -> new_time
   #   - self - other_time -> float
   # -->
-  # When `numeric` is given, returns a new Time object whose value is the
+  # 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
@@ -549,7 +712,7 @@ class Time < Object
   #     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`:
+  # the numeric values of `self` and `other_time` in seconds:
   #
   #     t - t # => 0.0
   #
@@ -606,8 +769,6 @@ class Time < Object
   #     t.strftime('%a %b %e %T %Y') # => "Sun Dec 31 23:59:59 2000"
   #     t.strftime('%c')             # => "Sun Dec 31 23:59:59 2000"
   #
-  # Time#asctime is an alias for Time#ctime.
-  #
   # Related: Time#to_s, Time#inspect:
   #
   #     t.inspect                    # => "2000-12-31 23:59:59.5 +000001"
@@ -628,8 +789,6 @@ class Time < Object
   #     t.strftime('%a %b %e %T %Y') # => "Sun Dec 31 23:59:59 2000"
   #     t.strftime('%c')             # => "Sun Dec 31 23:59:59 2000"
   #
-  # Time#asctime is an alias for Time#ctime.
-  #
   # Related: Time#to_s, Time#inspect:
   #
   #     t.inspect                    # => "2000-12-31 23:59:59.5 +000001"
@@ -644,8 +803,6 @@ class Time < Object
   #     # => 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.
   #
   def day: () -> Integer
@@ -695,16 +852,14 @@ class Time < Object
   #     t.zone                     # => "Central Daylight Time"
   #     t.dst?                     # => true
   #
-  # Time#isdst is an alias for Time#dst?.
-  #
   def dst?: () -> bool
 
   # <!--
   #   rdoc-file=time.c
   #   - eql?(other_time)
   # -->
-  # Returns `true` if `self` and `other_time` are both Time objects with the exact
-  # same time value.
+  # Returns `true` if `self` and `other_time` are both `Time` objects with the
+  # exact same time value.
   #
   def eql?: (untyped arg0) -> bool
 
@@ -725,7 +880,7 @@ class Time < Object
   #   rdoc-file=time.c
   #   - getutc -> new_time
   # -->
-  # Returns a new Time object representing the value of `self` converted to the
+  # Returns a new `Time` object representing the value of `self` converted to the
   # UTC timezone:
   #
   #     local = Time.local(2000) # => 2000-01-01 00:00:00 -0600
@@ -734,15 +889,13 @@ class Time < Object
   #     utc.utc?                 # => true
   #     utc == local             # => true
   #
-  # Time#getgm is an alias for Time#getutc.
-  #
   def getgm: () -> Time
 
   # <!--
   #   rdoc-file=time.c
   #   - getlocal(zone = nil) -> new_time
   # -->
-  # Returns a new Time object representing the value of `self` converted to a
+  # Returns a new `Time` object representing the value of `self` converted to a
   # given timezone; if `zone` is `nil`, the local timezone is used:
   #
   #     t = Time.utc(2000)                    # => 2000-01-01 00:00:00 UTC
@@ -750,12 +903,12 @@ class Time < Object
   #     t.getlocal('+12:00')                  # => 2000-01-01 12:00:00 +1200
   #
   # For forms of argument `zone`, see [Timezone
-  # Specifiers](rdoc-ref:timezones.rdoc).
+  # Specifiers](rdoc-ref:Time@Timezone+Specifiers).
   #
   def getlocal: (?Integer utc_offset) -> Time
 
   # <!-- rdoc-file=time.c -->
-  # Returns a new Time object representing the value of `self` converted to the
+  # Returns a new `Time` object representing the value of `self` converted to the
   # UTC timezone:
   #
   #     local = Time.local(2000) # => 2000-01-01 00:00:00 -0600
@@ -764,8 +917,6 @@ class Time < Object
   #     utc.utc?                 # => true
   #     utc == local             # => true
   #
-  # Time#getgm is an alias for Time#getutc.
-  #
   def getutc: () -> Time
 
   # <!-- rdoc-file=time.c -->
@@ -778,8 +929,6 @@ class Time < Object
   #     # => 2000-01-01 20:15:01 UTC
   #     utc.utc? # => true
   #
-  # Time#gmt? is an alias for Time#utc?.
-  #
   # Related: Time.utc.
   #
   def gmt?: () -> bool
@@ -790,8 +939,6 @@ class Time < Object
   #     Time.utc(2000, 1, 1).utc_offset   # => 0
   #     Time.local(2000, 1, 1).utc_offset # => -21600 # -6*3600, or minus six hours.
   #
-  # Time#gmt_offset and Time#gmtoff are aliases for Time#utc_offset.
-  #
   def gmt_offset: () -> Integer
 
   # <!--
@@ -805,9 +952,7 @@ class Time < Object
   #     t.utc              # => 2000-01-01 06:00:00 UTC
   #     t.utc?             # => true
   #
-  # Time#gmtime is an alias for Time#utc.
-  #
-  # Related: Time#getutc (returns a new converted Time object).
+  # Related: Time#getutc (returns a new converted `Time` object).
   #
   def gmtime: () -> Time
 
@@ -837,16 +982,16 @@ class Time < Object
 
   # <!--
   #   rdoc-file=timev.rb
-  #   - new(year = (now = true), mon = (str = year; nil), mday = nil, hour = nil, min = nil, sec = nil, zone = nil, in: nil, precision: 9)
+  #   - Time.new(year = nil, mon = nil, mday = nil, hour = nil, min = nil, sec = nil, zone = nil, in: nil, precision: 9)
   # -->
-  # Returns a new Time object based on the given arguments, by default in the
+  # Returns a new `Time` object based on the given arguments, by default in the
   # local timezone.
   #
   # With no positional arguments, returns the value of Time.now:
   #
   #     Time.new # => 2021-04-24 17:27:46.0512465 -0500
   #
-  # With one string argument that represents a time, returns a new Time object
+  # With one string argument that represents a time, returns a new `Time` object
   # based on the given argument, in the local timezone.
   #
   #     Time.new('2000-12-31 23:59:59.5')              # => 2000-12-31 23:59:59.5 -0600
@@ -855,7 +1000,7 @@ class Time < Object
   #     Time.new('2000-12-31 23:59:59.5')              # => 2000-12-31 23:59:59.5 -0600
   #     Time.new('2000-12-31 23:59:59.56789', precision: 3) # => 2000-12-31 23:59:59.567 -0600
   #
-  # With one to six arguments, returns a new Time object based on the given
+  # With one to six arguments, returns a new `Time` object based on the given
   # arguments, in the local timezone.
   #
   #     Time.new(2000, 1, 2, 3, 4, 5) # => 2000-01-02 03:04:05 -0600
@@ -918,8 +1063,8 @@ class Time < Object
   #
   #
   # When positional argument `zone` or keyword argument `in:` is given, the new
-  # Time object is in the specified timezone. For the forms of argument `zone`,
-  # see [Timezone Specifiers](rdoc-ref:timezones.rdoc):
+  # `Time` object is in the specified timezone. For the forms of argument `zone`,
+  # see [Timezone Specifiers](rdoc-ref:Time@Timezone+Specifiers):
   #
   #     Time.new(2000, 1, 1, 0, 0, 0, '+12:00')
   #     # => 2000-01-01 00:00:00 +1200
@@ -928,9 +1073,15 @@ class Time < Object
   #     Time.new(in: '-12:00')
   #     # => 2022-08-23 08:49:26.1941467 -1200
   #
+  # Since `in:` keyword argument just provides the default, so if the first
+  # argument in single string form contains time zone information, this keyword
+  # argument will be silently ignored.
+  #
+  #     Time.new('2000-01-01 00:00:00 +0100', in: '-0500').utc_offset  # => 3600
+  #
   # *   `precision`: maximum effective digits in sub-second part, default is 9.
-  #     More digits will be truncated, as other operations of Time. Ignored unless
-  #     the first argument is a string.
+  #     More digits will be truncated, as other operations of `Time`. Ignored
+  #     unless the first argument is a string.
   #
   def initialize: (?Integer? year, ?Integer? month, ?Integer? day, ?Integer? hour, ?Integer? min, ?Numeric? sec, ?String | Integer | nil) -> void
                 | (?Integer? year, ?Integer? month, ?Integer? day, ?Integer? hour, ?Integer? min, ?Numeric? sec, in: String | Integer | nil) -> void
@@ -965,8 +1116,6 @@ class Time < Object
   #     t.zone                     # => "Central Daylight Time"
   #     t.dst?                     # => true
   #
-  # Time#isdst is an alias for Time#dst?.
-  #
   def isdst: () -> bool
 
   # <!--
@@ -977,20 +1126,20 @@ class Time < Object
   # With no argument given:
   #
   # *   Returns `self` if `self` is a local time.
-  # *   Otherwise returns a new Time in the user's local timezone:
+  # *   Otherwise returns a new `Time` in the user's local timezone:
   #
   #         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
   #
   #
-  # With argument `zone` given, returns the new Time object created by converting
-  # `self` to the given time zone:
+  # With argument `zone` given, returns the new `Time` object created by
+  # converting `self` to the given time zone:
   #
   #     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:timezones.rdoc).
+  # Specifiers](rdoc-ref:Time@Timezone+Specifiers).
   #
   def localtime: (?String utc_offset) -> Time
 
@@ -1004,8 +1153,6 @@ class Time < Object
   #     # => 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.
   #
   def mday: () -> Integer
@@ -1034,8 +1181,6 @@ class Time < Object
   #     # => 2000-01-02 03:04:05 +000006
   #     t.mon # => 1
   #
-  # Time#month is an alias for Time#mday.
-  #
   # Related: Time#year, Time#hour, Time#min.
   #
   def mon: () -> Integer
@@ -1062,15 +1207,13 @@ class Time < Object
   #
   # Related: Time#subsec (returns exact subseconds).
   #
-  # Time#tv_nsec is an alias for Time#usec.
-  #
   def nsec: () -> Integer
 
   # <!--
   #   rdoc-file=time.c
   #   - round(ndigits = 0) -> new_time
   # -->
-  # Returns a new Time object whose numeric value is that of `self`, with its
+  # 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)
@@ -1188,7 +1331,7 @@ class Time < Object
   #     #    [sec, min, hour, day, mon, year, wday, yday, dst?,   zone]
   #
   # The returned array is suitable for use as an argument to Time.utc or
-  # Time.local to create a new Time object.
+  # Time.local to create a new `Time` object.
   #
   def to_a: () -> [ Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, bool, String ]
 
@@ -1223,8 +1366,6 @@ class Time < Object
   #     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.
   #
   def to_i: () -> Integer
@@ -1283,8 +1424,6 @@ class Time < Object
   #
   # Related: Time#subsec (returns exact subseconds).
   #
-  # Time#tv_nsec is an alias for Time#usec.
-  #
   def tv_nsec: () -> Integer
 
   # <!-- rdoc-file=time.c -->
@@ -1296,8 +1435,6 @@ class Time < Object
   #     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.
   #
   def tv_sec: () -> Integer
@@ -1314,8 +1451,6 @@ class Time < Object
   #
   # Related: Time#subsec (returns exact subseconds).
   #
-  # Time#tv_usec is an alias for Time#usec.
-  #
   def tv_usec: () -> Integer
 
   # <!-- rdoc-file=time.c -->
@@ -1327,8 +1462,6 @@ class Time < Object
   #
   # Related: Time#subsec (returns exact subseconds).
   #
-  # Time#tv_usec is an alias for Time#usec.
-  #
   def usec: () -> Integer
 
   # <!-- rdoc-file=time.c -->
@@ -1339,9 +1472,7 @@ class Time < Object
   #     t.utc              # => 2000-01-01 06:00:00 UTC
   #     t.utc?             # => true
   #
-  # Time#gmtime is an alias for Time#utc.
-  #
-  # Related: Time#getutc (returns a new converted Time object).
+  # Related: Time#getutc (returns a new converted `Time` object).
   #
   def utc: () -> Time
 
@@ -1358,8 +1489,6 @@ class Time < Object
   #     # => 2000-01-01 20:15:01 UTC
   #     utc.utc? # => true
   #
-  # Time#gmt? is an alias for Time#utc?.
-  #
   # Related: Time.utc.
   #
   def utc?: () -> bool
@@ -1370,8 +1499,6 @@ class Time < Object
   #     Time.utc(2000, 1, 1).utc_offset   # => 0
   #     Time.local(2000, 1, 1).utc_offset # => -21600 # -6*3600, or minus six hours.
   #
-  # Time#gmt_offset and Time#gmtoff are aliases for Time#utc_offset.
-  #
   def utc_offset: () -> Integer
 
   # <!--
@@ -1440,7 +1567,7 @@ class Time < Object
   def zone: () -> String
 
   # <!-- rdoc-file=time.c -->
-  # Like Time.utc, except that the returned Time object has the local timezone,
+  # Like Time.utc, except that the returned `Time` object has the local timezone,
   # not the UTC timezone:
   #
   #     # With seven arguments.
@@ -1461,8 +1588,6 @@ class Time < Object
   #     Time.utc(2000, 1, 1).utc_offset   # => 0
   #     Time.local(2000, 1, 1).utc_offset # => -21600 # -6*3600, or minus six hours.
   #
-  # Time#gmt_offset and Time#gmtoff are aliases for Time#utc_offset.
-  #
   def gmtoff: () -> Integer
 
   # <!-- rdoc-file=time.c -->
@@ -1472,8 +1597,6 @@ class Time < Object
   #     # => 2000-01-02 03:04:05 +000006
   #     t.mon # => 1
   #
-  # Time#month is an alias for Time#mday.
-  #
   # Related: Time#year, Time#hour, Time#min.
   #
   def month: () -> Integer
@@ -1482,7 +1605,7 @@ class Time < Object
   #   rdoc-file=time.c
   #   - floor(ndigits = 0) -> new_time
   # -->
-  # Returns a new Time object whose numerical value is less than or equal to
+  # 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)
@@ -1509,7 +1632,7 @@ class Time < Object
   #   rdoc-file=time.c
   #   - ceil(ndigits = 0)   -> new_time
   # -->
-  # Returns a new Time object whose numerical value is greater than or equal to
+  # 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)