rbs 2.8.4 → 3.8.1

data/core/integer.rbs

@@ -3,14 +3,11 @@
 #
 # You can create an Integer object explicitly with:
 #
-# *   An [integer
-#     literal](doc/syntax/literals_rdoc.html#label-Integer+Literals).
-#
+# *   An [integer literal](rdoc-ref:syntax/literals.rdoc@Integer+Literals).
 #
 # You can convert certain objects to Integers with:
 #
-# *   Method [Integer](Kernel.html#method-i-Integer).
-#
+# *   Method #Integer.
 #
 # An attempt to add a singleton method to an instance of this class causes an
 # exception to be raised.
@@ -19,161 +16,81 @@
 #
 # First, what's elsewhere. Class Integer:
 #
-# *   Inherits from [class
-#     Numeric](Numeric.html#class-Numeric-label-What-27s+Here).
-#
+# *   Inherits from [class Numeric](rdoc-ref:Numeric@What-27s+Here) and [class
+#     Object](rdoc-ref:Object@What-27s+Here).
+# *   Includes [module Comparable](rdoc-ref:Comparable@What-27s+Here).
 #
 # Here, class Integer provides methods for:
 #
-# *   [Querying](#class-Integer-label-Querying)
-# *   [Comparing](#class-Integer-label-Comparing)
-# *   [Converting](#class-Integer-label-Converting)
-# *   [Other](#class-Integer-label-Other)
-#
+# *   [Querying](rdoc-ref:Integer@Querying)
+# *   [Comparing](rdoc-ref:Integer@Comparing)
+# *   [Converting](rdoc-ref:Integer@Converting)
+# *   [Other](rdoc-ref:Integer@Other)
 #
 # ### Querying
 #
-#     #allbits?
-# :       Returns whether all bits in `self` are set.
-#
-#     #anybits?
-# :       Returns whether any bits in `self` are set.
-#
-#     #nobits?
-# :       Returns whether no bits in `self` are set.
-#
-#
+# *   #allbits?: Returns whether all bits in `self` are set.
+# *   #anybits?: Returns whether any bits in `self` are set.
+# *   #nobits?: Returns whether no bits in `self` are set.
 #
 # ### Comparing
 #
-#     [<](#method-i-3C)
-# :       Returns whether `self` is less than the given value.
-#
-#     [<=](#method-i-3C-3D)
-# :       Returns whether `self` is less than or equal to the given value.
-#
-#     [<=>](#method-i-3C-3D-3E)
-# :       Returns a number indicating whether `self` is less than, equal to, or
-#         greater than the given value.
-#
-#     [==](#method-i-3D-3D) (aliased as #===)
-# :       Returns whether `self` is equal to the given value.
-#
-#     [>](#method-i-3E)
-# :       Returns whether `self` is greater than the given value.
-#
-#     [>=](#method-i-3E-3D)
-# :       Returns whether `self` is greater than or equal to the given value.
-#
+# *   #<: Returns whether `self` is less than the given value.
+# *   #<=: Returns whether `self` is less than or equal to the given value.
+# *   #<=>: Returns a number indicating whether `self` is less than, equal to,
+#     or greater than the given value.
+# *   #== (aliased as #===): Returns whether `self` is equal to the given
+#         value.
 #
+# *   #>: Returns whether `self` is greater than the given value.
+# *   #>=: Returns whether `self` is greater than or equal to the given value.
 #
 # ### Converting
 #
-#     ::sqrt
-# :       Returns the integer square root of the given value.
-#
-#     ::try_convert
-# :       Returns the given value converted to an Integer.
-#
-#     #% (aliased as #modulo)
-# :       Returns `self` modulo the given value.
-#
-#     [&](#method-i-26)
-# :       Returns the bitwise AND of `self` and the given value.
-#
-#     #*
-# :       Returns the product of `self` and the given value.
-#
-#     [**](#method-i-2A-2A)
-# :       Returns the value of `self` raised to the power of the given value.
-#
-#     #+
-# :       Returns the sum of `self` and the given value.
-#
-#     #-
-# :       Returns the difference of `self` and the given value.
-#
-#     [/](#method-i-2F)
-# :       Returns the quotient of `self` and the given value.
-#
-#     #<<
-# :       Returns the value of `self` after a leftward bit-shift.
-#
-#     #>>
-# :       Returns the value of `self` after a rightward bit-shift.
-#
-#     #[]
-# :       Returns a slice of bits from `self`.
-#
-#     [^](#method-i-5E)
-# :       Returns the bitwise EXCLUSIVE OR of `self` and the given value.
-#
-#     #ceil
-# :       Returns the smallest number greater than or equal to `self`.
-#
-#     #chr
-# :       Returns a 1-character string containing the character represented by
-#         the value of `self`.
-#
-#     #digits
-# :       Returns an array of integers representing the base-radix digits of
-#         `self`.
-#
-#     #div
-# :       Returns the integer result of dividing `self` by the given value.
-#
-#     #divmod
-# :       Returns a 2-element array containing the quotient and remainder
-#         results of dividing `self` by the given value.
-#
-#     #fdiv
-# :       Returns the Float result of dividing `self` by the given value.
-#
-#     #floor
-# :       Returns the greatest number smaller than or equal to `self`.
-#
-#     #pow
-# :       Returns the modular exponentiation of `self`.
-#
-#     #pred
-# :       Returns the integer predecessor of `self`.
-#
-#     #remainder
-# :       Returns the remainder after dividing `self` by the given value.
-#
-#     #round
-# :       Returns `self` rounded to the nearest value with the given precision.
-#
-#     #succ (aliased as #next)
-# :       Returns the integer successor of `self`.
-#
-#     #to_f
-# :       Returns `self` converted to a Float.
-#
-#     #to_s (aliased as #inspect)
-# :       Returns a string containing the place-value representation of `self`
-#         in the given radix.
-#
-#     #truncate
-# :       Returns `self` truncated to the given precision.
-#
-#     [/](#method-i-7C)
-# :       Returns the bitwise OR of `self` and the given value.
-#
-#
+# *   ::sqrt: Returns the integer square root of the given value.
+# *   ::try_convert: Returns the given value converted to an Integer.
+# *   #% (aliased as #modulo): Returns `self` modulo the given value.
+# *   #&: Returns the bitwise AND of `self` and the given value.
+# *   #*: Returns the product of `self` and the given value.
+# *   #**: Returns the value of `self` raised to the power of the given value.
+# *   #+: Returns the sum of `self` and the given value.
+# *   #-: Returns the difference of `self` and the given value.
+# *   #/: Returns the quotient of `self` and the given value.
+# *   #<<: Returns the value of `self` after a leftward bit-shift.
+# *   #>>: Returns the value of `self` after a rightward bit-shift.
+# *   #[]: Returns a slice of bits from `self`.
+# *   #^: Returns the bitwise EXCLUSIVE OR of `self` and the given value.
+# *   #|: Returns the bitwise OR of `self` and the given value.
+# *   #ceil: Returns the smallest number greater than or equal to `self`.
+# *   #chr: Returns a 1-character string containing the character represented by
+#     the value of `self`.
+# *   #digits: Returns an array of integers representing the base-radix digits
+#     of `self`.
+# *   #div: Returns the integer result of dividing `self` by the given value.
+# *   #divmod: Returns a 2-element array containing the quotient and remainder
+#     results of dividing `self` by the given value.
+# *   #fdiv: Returns the Float result of dividing `self` by the given value.
+# *   #floor: Returns the greatest number smaller than or equal to `self`.
+# *   #pow: Returns the modular exponentiation of `self`.
+# *   #pred: Returns the integer predecessor of `self`.
+# *   #remainder: Returns the remainder after dividing `self` by the given
+#     value.
+# *   #round: Returns `self` rounded to the nearest value with the given
+#     precision.
+# *   #succ (aliased as #next): Returns the integer successor of `self`.
+# *   #to_f: Returns `self` converted to a Float.
+# *   #to_s (aliased as #inspect): Returns a string containing the place-value
+#     representation of `self` in the given radix.
+# *   #truncate: Returns `self` truncated to the given precision.
 #
 # ### Other
 #
-#     #downto
-# :       Calls the given block with each integer value from `self` down to the
-#         given value.
-#
-#     #times
-# :       Calls the given block `self` times with each integer in `(0..self-1)`.
-#
-#     #upto
-# :       Calls the given block with each integer value from `self` up to the
-#         given value.
+# *   #downto: Calls the given block with each integer value from `self` down to
+#     the given value.
+# *   #times: Calls the given block `self` times with each integer in
+#     `(0..self-1)`.
+# *   #upto: Calls the given block with each integer value from `self` up to the
+#     given value.
 #
 class Integer < Numeric
   # <!--
@@ -209,7 +126,7 @@ class Integer < Numeric
   def self.sqrt: (int n) -> Integer
 
   # <!--
-  #   rdoc-file=numeric.rb
+  #   rdoc-file=numeric.c
   #   - Integer.try_convert(object) -> object, integer, or nil
   # -->
   # If `object` is an Integer object, returns `object`.
@@ -227,8 +144,6 @@ class Integer < Numeric
   def self.try_convert: (int) -> Integer
                       | (untyped) -> Integer?
 
-  public
-
   # <!--
   #   rdoc-file=numeric.c
   #   - self % other -> real_number
@@ -256,8 +171,6 @@ class Integer < Numeric
   #     10 % 3.0            # => 1.0
   #     10 % Rational(3, 1) # => (1/1)
   #
-  # Integer#modulo is an alias for Integer#%.
-  #
   def %: (Float) -> Float
        | (Rational) -> Rational
        | (Integer) -> Integer
@@ -355,9 +268,9 @@ class Integer < Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - -int  ->  integer
+  #   - -int -> integer
   # -->
-  # Returns `int`, negated.
+  # Returns `self`, negated.
   #
   def -@: () -> Integer
 
@@ -444,7 +357,6 @@ class Integer < Numeric
   # *   1, if `self` is greater then `other`.
   # *   `nil`, if `self` and `other` are incomparable.
   #
-  #
   # Examples:
   #
   #     1 <=> 2              # => -1
@@ -469,8 +381,6 @@ class Integer < Numeric
   #
   # Related: Integer#eql? (requires `other` to be an Integer).
   #
-  # Integer#=== is an alias for Integer#==.
-  #
   def ==: (untyped) -> bool
 
   # <!--
@@ -484,8 +394,6 @@ class Integer < Numeric
   #
   # Related: Integer#eql? (requires `other` to be an Integer).
   #
-  # Integer#=== is an alias for Integer#==.
-  #
   def ===: (untyped) -> bool
 
   # <!--
@@ -597,16 +505,13 @@ class Integer < Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - int.abs        ->  integer
-  #   - int.magnitude  ->  integer
+  #   - abs -> integer
   # -->
-  # Returns the absolute value of `int`.
+  # Returns the absolute value of `self`.
   #
-  #     (-12345).abs   #=> 12345
-  #     -12345.abs     #=> 12345
-  #     12345.abs      #=> 12345
-  #
-  # Integer#magnitude is an alias for Integer#abs.
+  #     (-12345).abs # => 12345
+  #     -12345.abs   # => 12345
+  #     12345.abs    # => 12345
   #
   def abs: () -> Integer
 
@@ -664,44 +569,43 @@ class Integer < Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - int.bit_length  ->  integer
+  #   - bit_length -> integer
   # -->
-  # Returns the number of bits of the value of `int`.
-  #
-  # "Number of bits" means the bit position of the highest bit which is different
-  # from the sign bit (where the least significant bit has bit position 1). If
-  # there is no such bit (zero or minus one), zero is returned.
-  #
-  # I.e. this method returns *ceil(log2(int < 0 ? -int : int+1))*.
-  #
-  #     (-2**1000-1).bit_length   #=> 1001
-  #     (-2**1000).bit_length     #=> 1000
-  #     (-2**1000+1).bit_length   #=> 1000
-  #     (-2**12-1).bit_length     #=> 13
-  #     (-2**12).bit_length       #=> 12
-  #     (-2**12+1).bit_length     #=> 12
-  #     -0x101.bit_length         #=> 9
-  #     -0x100.bit_length         #=> 8
-  #     -0xff.bit_length          #=> 8
-  #     -2.bit_length             #=> 1
-  #     -1.bit_length             #=> 0
-  #     0.bit_length              #=> 0
-  #     1.bit_length              #=> 1
-  #     0xff.bit_length           #=> 8
-  #     0x100.bit_length          #=> 9
-  #     (2**12-1).bit_length      #=> 12
-  #     (2**12).bit_length        #=> 13
-  #     (2**12+1).bit_length      #=> 13
-  #     (2**1000-1).bit_length    #=> 1000
-  #     (2**1000).bit_length      #=> 1001
-  #     (2**1000+1).bit_length    #=> 1001
-  #
-  # This method can be used to detect overflow in Array#pack as follows:
+  # Returns the number of bits of the value of `self`, which is the bit position
+  # of the highest-order bit that is different from the sign bit (where the least
+  # significant bit has bit position 1). If there is no such bit (zero or minus
+  # one), returns zero.
+  #
+  # This method returns `ceil(log2(self < 0 ? -self : self + 1))`>.
+  #
+  #     (-2**1000-1).bit_length   # => 1001
+  #     (-2**1000).bit_length     # => 1000
+  #     (-2**1000+1).bit_length   # => 1000
+  #     (-2**12-1).bit_length     # => 13
+  #     (-2**12).bit_length       # => 12
+  #     (-2**12+1).bit_length     # => 12
+  #     -0x101.bit_length         # => 9
+  #     -0x100.bit_length         # => 8
+  #     -0xff.bit_length          # => 8
+  #     -2.bit_length             # => 1
+  #     -1.bit_length             # => 0
+  #     0.bit_length              # => 0
+  #     1.bit_length              # => 1
+  #     0xff.bit_length           # => 8
+  #     0x100.bit_length          # => 9
+  #     (2**12-1).bit_length      # => 12
+  #     (2**12).bit_length        # => 13
+  #     (2**12+1).bit_length      # => 13
+  #     (2**1000-1).bit_length    # => 1000
+  #     (2**1000).bit_length      # => 1001
+  #     (2**1000+1).bit_length    # => 1001
+  #
+  # For Integer *n*, this method can be used to detect overflow in Array#pack:
   #
   #     if n.bit_length < 32
-  #       [n].pack("l") # no overflow
+  #       [n].pack('l') # No overflow.
   #     else
-  #       raise "overflow"
+  #       raise 'Overflow'
   #     end
   #
   def bit_length: () -> Integer
@@ -710,26 +614,62 @@ class Integer < Numeric
   #   rdoc-file=numeric.c
   #   - ceil(ndigits = 0) -> integer
   # -->
-  # Returns the smallest number greater than or equal to `self` with a precision
-  # of `ndigits` decimal digits.
-  #
-  # When the precision is negative, the returned value is an integer with at least
-  # `ndigits.abs` trailing zeros:
+  # Returns an integer that is a "ceiling" value for `self`,
+  # as specified by the given `ndigits`,
+  # which must be an
+  # [integer-convertible
+  # object](rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects).
+  # *   When `self` is zero, returns zero (regardless of the value of `ndigits`):
+  #         0.ceil(2)  # => 0
+  # 0.ceil(-2) # => 0
+  #
+  # *   When `self` is non-zero and `ndigits` is non-negative, returns `self`:
+  #         555.ceil     # => 555
+  # 555.ceil(50) # => 555
+  #
+  # *   When `self` is non-zero and `ndigits` is negative,
+  #      returns a value based on a computed granularity:
+  #     *   The granularity is `10 ** ndigits.abs`.
+  #     *   The returned value is the smallest multiple of the granularity
+  #          that is greater than or equal to `self`.
+  #     Examples with positive `self`:
+  # ndigits|Granularity|1234.ceil(ndigits)
+  # -------|-----------|------------------
+  #      -1|         10|              1240
+  #      -2|        100|              1300
+  #      -3|       1000|              2000
+  #      -4|      10000|             10000
+  #      -5|     100000|            100000
+  #     Examples with negative `self`:
+  # ndigits|Granularity|-1234.ceil(ndigits)
+  # -------|-----------|-------------------
+  #      -1|         10|              -1230
+  #      -2|        100|              -1200
+  #      -3|       1000|              -1000
+  #      -4|      10000|                  0
+  #      -5|     100000|                  0
+  # Related: Integer#floor.
   #
-  #     555.ceil(-1)  # => 560
-  #     555.ceil(-2)  # => 600
-  #     -555.ceil(-2) # => -500
-  #     555.ceil(-3)  # => 1000
+  def ceil: () -> Integer
+          | (int digits) -> (Integer | Float)
+
+  # <!--
+  #   rdoc-file=numeric.rb
+  #   - ceildiv(numeric) -> integer
+  # -->
+  # Returns the result of division `self` by `numeric`. rounded up to the nearest
+  # integer.
   #
-  # Returns `self` when `ndigits` is zero or positive.
+  #     3.ceildiv(3)   # => 1
+  #     4.ceildiv(3)   # => 2
   #
-  #     555.ceil     # => 555
-  #     555.ceil(50) # => 555
+  #     4.ceildiv(-3)  # => -1
+  #     -4.ceildiv(3)  # => -1
+  #     -4.ceildiv(-3) # => 2
   #
-  # Related: Integer#floor.
+  #     3.ceildiv(1.2) # => 3
   #
-  def ceil: () -> Integer
-          | (int digits) -> (Integer | Float)
+  def ceildiv: (Numeric other) -> Integer
 
   # <!--
   #   rdoc-file=numeric.c
@@ -740,7 +680,7 @@ class Integer < Numeric
   # of `self`, according to the given `encoding`.
   #
   #     65.chr                   # => "A"
-  #     0..chr                   # => "\x00"
+  #     0.chr                    # => "\x00"
   #     255.chr                  # => "\xFF"
   #     string = 255.chr(Encoding::UTF_8)
   #     string.encoding          # => Encoding::UTF_8
@@ -753,14 +693,14 @@ class Integer < Numeric
 
   # <!--
   #   rdoc-file=bignum.c
-  #   - big.coerce(numeric)  ->  array
+  #   - int.coerce(numeric)  ->  array
   # -->
-  # Returns an array with both a `numeric` and a `big` represented as Bignum
-  # objects.
+  # Returns an array with both a `numeric` and a `int` represented as Integer
+  # objects or Float objects.
   #
-  # This is achieved by converting `numeric` to a Bignum.
+  # This is achieved by converting `numeric` to an Integer or a Float.
   #
-  # A TypeError is raised if the `numeric` is not a Fixnum or Bignum type.
+  # A TypeError is raised if the `numeric` is not an Integer or a Float type.
   #
   #     (0x3FFFFFFFFFFFFFFF+1).coerce(42)   #=> [42, 4611686018427387904]
   #
@@ -771,10 +711,10 @@ class Integer < Numeric
   def conjugate: () -> Integer
 
   # <!--
-  #   rdoc-file=rational.c
-  #   - int.denominator  ->  1
+  #   rdoc-file=numeric.rb
+  #   - denominator -> 1
   # -->
-  # Returns 1.
+  # Returns `1`.
   #
   def denominator: () -> Integer
 
@@ -800,14 +740,14 @@ class Integer < Numeric
   # Performs integer division; returns the integer result of dividing `self` by
   # `numeric`:
   #
-  #       4.div(3)      # => 1
-  #       4.div(-3)      # => -2
-  #       -4.div(3)      # => -2
-  #       -4.div(-3)      # => 1
-  #       4.div(3.0)      # => 1
-  #       4.div(Rational(3, 1))      # => 1
+  #     4.div(3)              # => 1
+  #     4.div(-3)             # => -2
+  #     -4.div(3)             # => -2
+  #     -4.div(-3)            # => 1
+  #     4.div(3.0)            # => 1
+  #     4.div(Rational(3, 1)) # => 1
   #
-  #     Raises an exception if +numeric+ does not have method +div+.
+  # Raises an exception if `numeric` does not have method `div`.
   #
   def div: (Numeric) -> Integer
 
@@ -836,7 +776,8 @@ class Integer < Numeric
   #     13.divmod(Rational(4, 1)) # => [3, (1/1)]
   #
   def divmod: (Integer) -> [ Integer, Integer ]
-            | (Float) -> [ Float, Float ]
+            | (Float) -> [ Integer, Float ]
+            | (Rational) -> [ Integer, Rational ]
             | (Numeric) -> [ Numeric, Numeric ]
 
   # <!--
@@ -866,9 +807,9 @@ class Integer < Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - int.even?  ->  true or false
+  #   - even? -> true or false
   # -->
-  # Returns `true` if `int` is an even number.
+  # Returns `true` if `self` is an even number, `false` otherwise.
   #
   def even?: () -> bool
 
@@ -894,22 +835,40 @@ class Integer < Numeric
   #   rdoc-file=numeric.c
   #   - floor(ndigits = 0) -> integer
   # -->
-  # Returns the largest number less than or equal to `self` with a precision of
-  # `ndigits` decimal digits.
-  #
-  # When `ndigits` is negative, the returned value has at least `ndigits.abs`
-  # trailing zeros:
-  #
-  #     555.floor(-1)  # => 550
-  #     555.floor(-2)  # => 500
-  #     -555.floor(-2) # => -600
-  #     555.floor(-3)  # => 0
-  #
-  # Returns `self` when `ndigits` is zero or positive.
-  #
-  #     555.floor     # => 555
-  #     555.floor(50) # => 555
-  #
+  # Returns an integer that is a "floor" value for `self`,
+  # as specified by the given `ndigits`,
+  # which must be an
+  # [integer-convertible
+  # object](rdoc-ref:implicit_conversion.rdoc@Integer-Convertible+Objects).
+  # *   When `self` is zero, returns zero (regardless of the value of `ndigits`):
+  #         0.floor(2)  # => 0
+  # 0.floor(-2) # => 0
+  #
+  # *   When `self` is non-zero and `ndigits` is non-negative, returns `self`:
+  #         555.floor     # => 555
+  # 555.floor(50) # => 555
+  #
+  # *   When `self` is non-zero and `ndigits` is negative,
+  #      returns a value based on a computed granularity:
+  #     *   The granularity is `10 ** ndigits.abs`.
+  #     *   The returned value is the largest multiple of the granularity
+  #          that is less than or equal to `self`.
+  #     Examples with positive `self`:
+  # ndigits|Granularity|1234.floor(ndigits)
+  # -------|-----------|-------------------
+  #      -1|         10|               1230
+  #      -2|        100|               1200
+  #      -3|       1000|               1000
+  #      -4|      10000|                  0
+  #      -5|     100000|                  0
+  #     Examples with negative `self`:
+  # ndigits|Granularity|-1234.floor(ndigits)
+  # -------|-----------|--------------------
+  #      -1|         10|               -1240
+  #      -2|        100|               -1300
+  #      -3|       1000|               -2000
+  #      -4|      10000|              -10000
+  #      -5|     100000|             -100000
   # Related: Integer#ceil.
   #
   def floor: (?int digits) -> Integer
@@ -964,15 +923,13 @@ class Integer < Numeric
   #
   # Raises an exception if `base` is out of range.
   #
-  # Integer#inspect is an alias for Integer#to_s.
-  #
   alias inspect to_s
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - int.integer?  ->  true
+  #   - integer? -> true
   # -->
-  # Since `int` is already an Integer, this always returns `true`.
+  # Since `self` is already an Integer, always returns `true`.
   #
   def integer?: () -> true
 
@@ -1021,8 +978,6 @@ class Integer < Numeric
   #     10 % 3.0            # => 1.0
   #     10 % Rational(3, 1) # => (1/1)
   #
-  # Integer#modulo is an alias for Integer#%.
-  #
   alias modulo %
 
   def negative?: () -> bool
@@ -1033,8 +988,6 @@ class Integer < Numeric
   #     1.succ  #=> 2
   #     -1.succ #=> 0
   #
-  # Integer#next is an alias for Integer#succ.
-  #
   # Related: Integer#pred (predecessor value).
   #
   def next: () -> Integer
@@ -1065,32 +1018,26 @@ class Integer < Numeric
   def nonzero?: () -> self?
 
   # <!--
-  #   rdoc-file=rational.c
-  #   - int.numerator  ->  self
+  #   rdoc-file=numeric.rb
+  #   - numerator -> self
   # -->
-  # Returns self.
+  # Returns `self`.
   #
   def numerator: () -> Integer
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - int.odd?  ->  true or false
+  #   - odd? -> true or false
   # -->
-  # Returns `true` if `int` is an odd number.
+  # Returns `true` if `self` is an odd number, `false` otherwise.
   #
   def odd?: () -> bool
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - int.ord  ->  self
+  #   - ord -> self
   # -->
-  # Returns the `int` itself.
-  #
-  #     97.ord   #=> 97
-  #
-  # This method is intended for compatibility to character literals in Ruby 1.9.
-  #
-  # For example, `?a.ord` returns 97 both in 1.8 and 1.9.
+  # Returns `self`; intended for compatibility to character literals in Ruby 1.9.
   #
   def ord: () -> Integer
 
@@ -1110,9 +1057,10 @@ class Integer < Numeric
   #     a.pow(b)     #=> same as a**b
   #     a.pow(b, m)  #=> same as (a**b) % m, but avoids huge temporary values
   #
-  def pow: (Integer other, ?Integer modulo) -> Integer
-         | (Float) -> Float
-         | (Rational) -> Rational
+  def pow: (Integer other) -> (Integer | Rational)
+         | (Integer other, Integer modulo) -> Integer
+         | (Float) -> (Float | Complex)
+         | (Rational) -> (Float | Rational | Complex)
          | (Complex) -> Complex
 
   # <!--
@@ -1218,7 +1166,6 @@ class Integer < Numeric
   #         15.round(-1, half: :even)    # => 20
   #         (-25).round(-1, half: :even) # => -20
   #
-  #
   # Raises and exception if the value for `half` is invalid.
   #
   # Related: Integer#truncate.
@@ -1228,19 +1175,17 @@ class Integer < Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - int.size  ->  int
+  #   - size -> integer
   # -->
-  # Document-method: Integer#size
-  #
-  # Returns the number of bytes in the machine representation of `int` (machine
-  # dependent).
+  # Returns the number of bytes in the machine representation of `self`; the value
+  # is system-dependent:
   #
-  #     1.size               #=> 8
-  #     -1.size              #=> 8
-  #     2147483647.size      #=> 8
-  #     (256**10 - 1).size   #=> 10
-  #     (256**20 - 1).size   #=> 20
-  #     (256**40 - 1).size   #=> 40
+  #     1.size             # => 8
+  #     -1.size            # => 8
+  #     2147483647.size    # => 8
+  #     (256**10 - 1).size # => 10
+  #     (256**20 - 1).size # => 20
+  #     (256**40 - 1).size # => 40
   #
   def size: () -> Integer
 
@@ -1250,10 +1195,10 @@ class Integer < Numeric
           | (to: Numeric, ?by: Integer) { (Integer) -> void } -> void
           | (by: Numeric, ?to: Numeric) { (Numeric) -> void } -> void
           | () -> Enumerator[Integer, bot]
-          | (Numeric limit, ?Integer step) -> Enumerator[Integer, void]
-          | (Numeric limit, ?Numeric step) -> Enumerator[Numeric, void]
-          | (to: Numeric, ?by: Integer) -> Enumerator[Integer, void]
-          | (by: Numeric, ?to: Numeric) -> Enumerator[Numeric, void]
+          | (Numeric limit, ?Integer step) -> Enumerator[Integer]
+          | (Numeric limit, ?Numeric step) -> Enumerator[Numeric]
+          | (to: Numeric, ?by: Integer) -> Enumerator[Integer]
+          | (by: Numeric, ?to: Numeric) -> Enumerator[Numeric]
 
   # <!--
   #   rdoc-file=numeric.c
@@ -1264,14 +1209,12 @@ class Integer < Numeric
   #     1.succ  #=> 2
   #     -1.succ #=> 0
   #
-  # Integer#next is an alias for Integer#succ.
-  #
   # Related: Integer#pred (predecessor value).
   #
   def succ: () -> Integer
 
   # <!--
-  #   rdoc-file=numeric.c
+  #   rdoc-file=numeric.rb
   #   - times {|i| ... } -> self
   #   - times            -> enumerator
   # -->
@@ -1306,19 +1249,17 @@ class Integer < Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - int.to_i    ->  integer
+  #   - to_i -> self
   # -->
-  # Since `int` is already an Integer, returns `self`.
-  #
-  # #to_int is an alias for #to_i.
+  # Returns `self` (which is already an Integer).
   #
   def to_i: () -> Integer
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - int.to_int  ->  integer
+  #   - to_int -> self
   # -->
-  # Since `int` is already an Integer, returns `self`.
+  # Returns `self` (which is already an Integer).
   #
   alias to_int to_i
 
@@ -1350,8 +1291,6 @@ class Integer < Numeric
   #
   # Raises an exception if `base` is out of range.
   #
-  # Integer#inspect is an alias for Integer#to_s.
-  #
   def to_s: () -> String
           | (2) -> String
           | (3) -> String
@@ -1437,9 +1376,9 @@ class Integer < Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - int.zero? -> true or false
+  #   - zero? -> true or false
   # -->
-  # Returns `true` if `int` has a zero value.
+  # Returns `true` if `self` has a zero value, `false` otherwise.
   #
   def zero?: () -> bool
 
@@ -1460,16 +1399,15 @@ class Integer < Numeric
 
   # <!--
   #   rdoc-file=numeric.rb
-  #   - ~int  ->  integer
+  #   - ~int -> integer
   # -->
-  # One's complement: returns a number where each bit is flipped.
+  # One's complement: returns the value of `self` with each bit inverted.
   #
-  # Inverts the bits in an Integer. As integers are conceptually of infinite
-  # length, the result acts as if it had an infinite number of one bits to the
-  # left. In hex representations, this is displayed as two periods to the left of
-  # the digits.
+  # Because an integer value is conceptually of infinite length, the result acts
+  # as if it had an infinite number of one bits to the left. In hex
+  # representations, this is displayed as two periods to the left of the digits:
   #
-  #     sprintf("%X", ~0x1122334455)    #=> "..FEEDDCCBBAA"
+  #     sprintf("%X", ~0x1122334455)    # => "..FEEDDCCBBAA"
   #
   def ~: () -> Integer
 end