rbs 2.0.0 → 2.1.0

data/core/integer.rbs

@@ -1,70 +1,332 @@
-# Holds Integer values.  You cannot add a singleton method to an Integer object,
-# any attempt to do so will raise a TypeError.
+# <!-- rdoc-file=numeric.c -->
+# An Integer object represents an integer value.
+#
+# You can create an Integer object explicitly with:
+#
+# *   An [integer
+#     literal](doc/syntax/literals_rdoc.html#label-Integer+Literals).
+#
+#
+# You can convert certain objects to Integers with:
+#
+# *   Method [Integer](Kernel.html#method-i-Integer).
+#
+#
+# An attempt to add a singleton method to an instance of this class causes an
+# exception to be raised.
+#
+# ## What's Here
+#
+# First, what's elsewhere. Class Integer:
+#
+# *   Inherits from [class
+#     Numeric](Numeric.html#class-Numeric-label-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
+#
+#     #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.
+#
+#
+#
+# ### 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.
+#
+#
+#
+# ### 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.
 #
 class Integer < Numeric
-  # Returns the integer square root of the non-negative integer `n`, i.e. the
-  # largest non-negative integer less than or equal to the square root of `n`.
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - Integer.sqrt(numeric) -> integer
+  # -->
+  # Returns the integer square root of the non-negative integer `n`, which is the
+  # largest non-negative integer less than or equal to the square root of
+  # `numeric`.
   #
-  #     Integer.sqrt(0)        #=> 0
-  #     Integer.sqrt(1)        #=> 1
-  #     Integer.sqrt(24)       #=> 4
-  #     Integer.sqrt(25)       #=> 5
-  #     Integer.sqrt(10**400)  #=> 10**200
+  #     Integer.sqrt(0)       # => 0
+  #     Integer.sqrt(1)       # => 1
+  #     Integer.sqrt(24)      # => 4
+  #     Integer.sqrt(25)      # => 5
+  #     Integer.sqrt(10**400) # => 10**200
   #
-  # Equivalent to `Math.sqrt(n).floor`, except that the result of the latter code
-  # may differ from the true value due to the limited precision of floating point
-  # arithmetic.
+  # If `numeric` is not an Integer, it is converted to an Integer:
   #
-  #     Integer.sqrt(10**46)     #=> 100000000000000000000000
-  #     Math.sqrt(10**46).floor  #=>  99999999999999991611392 (!)
+  #     Integer.sqrt(Complex(4, 0))  # => 2
+  #     Integer.sqrt(Rational(4, 1)) # => 2
+  #     Integer.sqrt(4.0)            # => 2
+  #     Integer.sqrt(3.14159)        # => 1
   #
-  # If `n` is not an Integer, it is converted to an Integer first. If `n` is
-  # negative, a Math::DomainError is raised.
+  # This method is equivalent to `Math.sqrt(numeric).floor`, except that the
+  # result of the latter code may differ from the true value due to the limited
+  # precision of floating point arithmetic.
+  #
+  #     Integer.sqrt(10**46)    # => 100000000000000000000000
+  #     Math.sqrt(10**46).floor # => 99999999999999991611392
+  #
+  # Raises an exception if `numeric` is negative.
   #
   def self.sqrt: (int n) -> Integer
 
+  # <!--
+  #   rdoc-file=numeric.rb
+  #   - Integer.try_convert(object) -> object, integer, or nil
+  # -->
+  # If `object` is an Integer object, returns `object`.
+  #     Integer.try_convert(1) # => 1
+  #
+  # Otherwise if `object` responds to `:to_int`, calls `object.to_int` and returns
+  # the result.
+  #     Integer.try_convert(1.25) # => 1
+  #
+  # Returns `nil` if `object` does not respond to `:to_int`
+  #     Integer.try_convert([]) # => nil
+  #
+  # Raises an exception unless `object.to_int` returns an Integer object.
+  #
+  def self.try_convert: (int) -> Integer
+                      | (untyped) -> Integer?
+
   public
 
-  # Returns `int` modulo `other`.
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - self % other -> real_number
+  # -->
+  # Returns `self` modulo `other` as a real number.
+  #
+  # For integer `n` and real number `r`, these expressions are equivalent:
   #
-  # See Numeric#divmod for more information.
+  #     n % r
+  #     n-r*(n/r).floor
+  #     n.divmod(r)[1]
+  #
+  # See Numeric#divmod.
+  #
+  # Examples:
+  #
+  #     10 % 2              # => 0
+  #     10 % 3              # => 1
+  #     10 % 4              # => 2
+  #
+  #     10 % -2             # => 0
+  #     10 % -3             # => -2
+  #     10 % -4             # => -2
+  #
+  #     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
        | (Numeric) -> Numeric
 
-  # Bitwise AND.
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - self & other ->  integer
+  # -->
+  # Bitwise AND; each bit in the result is 1 if both corresponding bits in `self`
+  # and `other` are 1, 0 otherwise:
+  #
+  #     "%04b" % (0b0101 & 0b0110) # => "0100"
+  #
+  # Raises an exception if `other` is not an Integer.
+  #
+  # Related: Integer#| (bitwise OR), Integer#^ (bitwise EXCLUSIVE OR).
   #
   def &: (Integer) -> Integer
 
-  # Performs multiplication: the class of the resulting object depends on the
-  # class of `numeric`.
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - self * numeric -> numeric_result
+  # -->
+  # Performs multiplication:
+  #
+  #     4 * 2              # => 8
+  #     4 * -2             # => -8
+  #     -4 * 2             # => -8
+  #     4 * 2.0            # => 8.0
+  #     4 * Rational(1, 3) # => (4/3)
+  #     4 * Complex(2, 0)  # => (8+0i)
   #
   def *: (Float) -> Float
        | (Rational) -> Rational
        | (Complex) -> Complex
        | (Integer) -> Integer
 
-  # Raises `int` to the power of `numeric`, which may be negative or fractional.
-  # The result may be an Integer, a Float, a Rational, or a complex number.
-  #
-  #     2 ** 3        #=> 8
-  #     2 ** -1       #=> (1/2)
-  #     2 ** 0.5      #=> 1.4142135623730951
-  #     (-1) ** 0.5   #=> (0.0+1.0i)
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - self ** numeric -> numeric_result
+  # -->
+  # Raises `self` to the power of `numeric`:
   #
-  #     123456789 ** 2     #=> 15241578750190521
-  #     123456789 ** 1.2   #=> 5126464716.0993185
-  #     123456789 ** -2    #=> (1/15241578750190521)
+  #     2 ** 3              # => 8
+  #     2 ** -3             # => (1/8)
+  #     -2 ** 3             # => -8
+  #     -2 ** -3            # => (-1/8)
+  #     2 ** 3.3            # => 9.849155306759329
+  #     2 ** Rational(3, 1) # => (8/1)
+  #     2 ** Complex(3, 0)  # => (8+0i)
   #
   def **: (Integer) -> Numeric
         | (Float) -> Numeric
         | (Rational) -> Numeric
         | (Complex) -> Complex
 
-  # Performs addition: the class of the resulting object depends on the class of
-  # `numeric`.
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - self + numeric -> numeric_result
+  # -->
+  # Performs addition:
+  #
+  #     2 + 2              # => 4
+  #     -2 + 2             # => 0
+  #     -2 + -2            # => -4
+  #     2 + 2.0            # => 4.0
+  #     2 + Rational(2, 1) # => (4/1)
+  #     2 + Complex(2, 0)  # => (4+0i)
   #
   def +: (Integer) -> Integer
        | (Float) -> Float
@@ -73,116 +335,271 @@ class Integer < Numeric
 
   def +@: () -> Integer
 
-  # Performs subtraction: the class of the resulting object depends on the class
-  # of `numeric`.
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - self - numeric -> numeric_result
+  # -->
+  # Performs subtraction:
+  #
+  #     4 - 2              # => 2
+  #     -4 - 2             # => -6
+  #     -4 - -2            # => -2
+  #     4 - 2.0            # => 2.0
+  #     4 - Rational(2, 1) # => (2/1)
+  #     4 - Complex(2, 0)  # => (2+0i)
   #
   def -: (Integer) -> Integer
        | (Float) -> Float
        | (Rational) -> Rational
        | (Complex) -> Complex
 
+  # <!--
+  #   rdoc-file=numeric.rb
+  #   - -int  ->  integer
+  # -->
   # Returns `int`, negated.
   #
   def -@: () -> Integer
 
-  # Performs division: the class of the resulting object depends on the class of
-  # `numeric`.
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - self / numeric -> numeric_result
+  # -->
+  # Performs division; for integer `numeric`, truncates the result to an integer:
+  #
+  #      4 / 3              # => 1
+  #      4 / -3             # => -2
+  #      -4 / 3             # => -2
+  #      -4 / -3            # => 1
+  #
+  #     For other +numeric+, returns non-integer result:
+  #
+  #      4 / 3.0            # => 1.3333333333333333
+  #      4 / Rational(3, 1) # => (4/3)
+  #      4 / Complex(3, 0)  # => ((4/3)+0i)
   #
   def /: (Integer) -> Integer
        | (Float) -> Float
        | (Rational) -> Rational
        | (Complex) -> Complex
 
-  # Returns `true` if the value of `int` is less than that of `real`.
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - self < other -> true or false
+  # -->
+  # Returns `true` if the value of `self` is less than that of `other`:
+  #
+  #       1 < 0              # => false
+  #       1 < 1              # => false
+  #       1 < 2              # => true
+  #       1 < 0.5            # => false
+  #       1 < Rational(1, 2) # => false
+  #
+  #     Raises an exception if the comparison cannot be made.
   #
   def <: (Numeric) -> bool
 
-  # Returns `int` shifted left `count` positions, or right if `count` is negative.
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - self << count -> integer
+  # -->
+  # Returns `self` with bits shifted `count` positions to the left, or to the
+  # right if `count` is negative:
+  #
+  #     n = 0b11110000
+  #     "%08b" % (n << 1)  # => "111100000"
+  #     "%08b" % (n << 3)  # => "11110000000"
+  #     "%08b" % (n << -1) # => "01111000"
+  #     "%08b" % (n << -3) # => "00011110"
+  #
+  # Related: Integer#>>.
   #
   def <<: (int) -> Integer
 
-  # Returns `true` if the value of `int` is less than or equal to that of `real`.
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - self <= real -> true or false
+  # -->
+  # Returns `true` if the value of `self` is less than or equal to that of
+  # `other`:
+  #
+  #     1 <= 0              # => false
+  #     1 <= 1              # => true
+  #     1 <= 2              # => true
+  #     1 <= 0.5            # => false
+  #     1 <= Rational(1, 2) # => false
+  #
+  # Raises an exception if the comparison cannot be made.
   #
   def <=: (Numeric) -> bool
 
-  # Comparison---Returns -1, 0, or +1 depending on whether `int` is less than,
-  # equal to, or greater than `numeric`.
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - self <=> other  ->  -1, 0, +1, or nil
+  # -->
+  # Returns:
   #
-  # This is the basis for the tests in the Comparable module.
+  # *   -1, if `self` is less than `other`.
+  # *   0, if `self` is equal to `other`.
+  # *   1, if `self` is greater then `other`.
+  # *   `nil`, if `self` and `other` are incomparable.
   #
-  # `nil` is returned if the two values are incomparable.
+  #
+  # Examples:
+  #
+  #     1 <=> 2              # => -1
+  #     1 <=> 1              # => 0
+  #     1 <=> 0              # => 1
+  #     1 <=> 'foo'          # => nil
+  #
+  #     1 <=> 1.0            # => 0
+  #     1 <=> Rational(1, 1) # => 0
+  #     1 <=> Complex(1, 0)  # => 0
+  #
+  # This method is the basis for comparisons in module Comparable.
   #
   def <=>: (Integer | Rational) -> Integer
          | (untyped) -> Integer?
 
-  # Returns `true` if `int` equals `other` numerically. Contrast this with
-  # Integer#eql?, which requires `other` to be an Integer.
+  # <!-- rdoc-file=numeric.c -->
+  # Returns `true` if `self` is numerically equal to `other`; `false` otherwise.
   #
   #     1 == 2     #=> false
   #     1 == 1.0   #=> true
   #
+  # Related: Integer#eql? (requires `other` to be an Integer).
+  #
+  # Integer#=== is an alias for Integer#==.
+  #
   def ==: (untyped) -> bool
 
-  # Returns `true` if `int` equals `other` numerically. Contrast this with
-  # Integer#eql?, which requires `other` to be an Integer.
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - self == other -> true or false
+  # -->
+  # Returns `true` if `self` is numerically equal to `other`; `false` otherwise.
   #
   #     1 == 2     #=> false
   #     1 == 1.0   #=> true
   #
+  # Related: Integer#eql? (requires `other` to be an Integer).
+  #
+  # Integer#=== is an alias for Integer#==.
+  #
   def ===: (untyped) -> bool
 
-  # Returns `true` if the value of `int` is greater than that of `real`.
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - self > other -> true or false
+  # -->
+  # Returns `true` if the value of `self` is greater than that of `other`:
+  #
+  #       1 > 0              # => true
+  #       1 > 1              # => false
+  #       1 > 2              # => false
+  #       1 > 0.5            # => true
+  #       1 > Rational(1, 2) # => true
+  #
+  #     Raises an exception if the comparison cannot be made.
   #
   def >: (Numeric) -> bool
 
-  # Returns `true` if the value of `int` is greater than or equal to that of
-  # `real`.
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - self >= real -> true or false
+  # -->
+  # Returns `true` if the value of `self` is greater than or equal to that of
+  # `other`:
+  #
+  #     1 >= 0              # => true
+  #     1 >= 1              # => true
+  #     1 >= 2              # => false
+  #     1 >= 0.5            # => true
+  #     1 >= Rational(1, 2) # => true
+  #
+  # Raises an exception if the comparison cannot be made.
   #
   def >=: (Numeric) -> bool
 
-  # Returns `int` shifted right `count` positions, or left if `count` is negative.
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - self >> count -> integer
+  # -->
+  # Returns `self` with bits shifted `count` positions to the right, or to the
+  # left if `count` is negative:
+  #
+  #     n = 0b11110000
+  #     "%08b" % (n >> 1)  # => "01111000"
+  #     "%08b" % (n >> 3)  # => "00011110"
+  #     "%08b" % (n >> -1) # => "111100000"
+  #     "%08b" % (n >> -3) # => "11110000000"
+  #
+  # Related: Integer#<<.
   #
   def >>: (int) -> Integer
 
-  # Bit Reference---Returns the `n`th bit in the binary representation of `int`,
-  # where `int[0]` is the least significant bit.
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - self[offset]    -> 0 or 1
+  #   - self[offset, size] -> integer
+  #   - self[range] -> integer
+  # -->
+  # Returns a slice of bits from `self`.
   #
-  #     a = 0b11001100101010
-  #     30.downto(0) {|n| print a[n] }
-  #     #=> 0000000000000000011001100101010
+  # With argument `offset`, returns the bit at the given offset, where offset 0
+  # refers to the least significant bit:
   #
-  #     a = 9**15
-  #     50.downto(0) {|n| print a[n] }
-  #     #=> 000101110110100000111000011110010100111100010111001
+  #     n = 0b10 # => 2
+  #     n[0]     # => 0
+  #     n[1]     # => 1
+  #     n[2]     # => 0
+  #     n[3]     # => 0
   #
-  # In principle, `n[i]` is equivalent to `(n >> i) & 1`. Thus, any negative index
+  # In principle, `n[i]` is equivalent to `(n >> i) & 1`. Thus, negative index
   # always returns zero:
   #
-  #     p 255[-1] #=> 0
+  #     255[-1] # => 0
+  #
+  # With arguments `offset` and `size`, returns `size` bits from `self`, beginning
+  # at `offset` and including bits of greater significance:
   #
-  # Range operations `n[i, len]` and `n[i..j]` are naturally extended.
+  #     n = 0b111000       # => 56
+  #     "%010b" % n[0, 10] # => "0000111000"
+  #     "%010b" % n[4, 10] # => "0000000011"
   #
-  # *   `n[i, len]` equals to `(n >> i) & ((1 << len) - 1)`.
-  # *   `n[i..j]` equals to `(n >> i) & ((1 << (j - i + 1)) - 1)`.
-  # *   `n[i...j]` equals to `(n >> i) & ((1 << (j - i)) - 1)`.
-  # *   `n[i..]` equals to `(n >> i)`.
-  # *   `n[..j]` is zero if `n & ((1 << (j + 1)) - 1)` is zero.  Otherwise, raises
-  #     an ArgumentError.
-  # *   `n[...j]` is zero if `n & ((1 << j) - 1)` is zero.  Otherwise, raises an
-  #     ArgumentError.
+  # With argument `range`, returns `range.size` bits from `self`, beginning at
+  # `range.begin` and including bits of greater significance:
   #
+  #     n = 0b111000      # => 56
+  #     "%010b" % n[0..9] # => "0000111000"
+  #     "%010b" % n[4..9] # => "0000000011"
   #
-  # Note that range operation may exhaust memory. For example, `-1[0,
-  # 1000000000000]` will raise NoMemoryError.
+  # Raises an exception if the slice cannot be constructed.
   #
   def []: (int) -> Integer
         | (int i, int len) -> Integer
         | (Range[int]) -> Integer
 
-  # Bitwise EXCLUSIVE OR.
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - self ^ other -> integer
+  # -->
+  # Bitwise EXCLUSIVE OR; each bit in the result is 1 if the corresponding bits in
+  # `self` and `other` are different, 0 otherwise:
+  #
+  #     "%04b" % (0b0101 ^ 0b0110) # => "0011"
+  #
+  # Raises an exception if `other` is not an Integer.
+  #
+  # Related: Integer#& (bitwise AND), Integer#| (bitwise OR).
   #
   def ^: (Integer) -> Integer
 
+  # <!--
+  #   rdoc-file=numeric.rb
+  #   - int.abs        ->  integer
+  #   - int.magnitude  ->  integer
+  # -->
   # Returns the absolute value of `int`.
   #
   #     (-12345).abs   #=> 12345
@@ -195,18 +612,60 @@ class Integer < Numeric
 
   def abs2: () -> Integer
 
-  # Returns `true` if all bits of `int & mask` are 1.
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - allbits?(mask) -> true or false
+  # -->
+  # Returns `true` if all bits that are set (=1) in `mask` are also set in `self`;
+  # returns `false` otherwise.
+  #
+  # Example values:
+  #
+  #     0b1010101  self
+  #     0b1010100  mask
+  #     0b1010100  self & mask
+  #          true  self.allbits?(mask)
+  #
+  #     0b1010100  self
+  #     0b1010101  mask
+  #     0b1010100  self & mask
+  #         false  self.allbits?(mask)
+  #
+  # Related: Integer#anybits?, Integer#nobits?.
   #
   def allbits?: (int mask) -> bool
 
   def angle: () -> (Integer | Float)
 
-  # Returns `true` if any bits of `int & mask` are 1.
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - anybits?(mask) -> true or false
+  # -->
+  # Returns `true` if any bit that is set (=1) in `mask` is also set in `self`;
+  # returns `false` otherwise.
+  #
+  # Example values:
+  #
+  #     0b10000010  self
+  #     0b11111111  mask
+  #     0b10000010  self & mask
+  #           true  self.anybits?(mask)
+  #
+  #     0b00000000  self
+  #     0b11111111  mask
+  #     0b00000000  self & mask
+  #          false  self.anybits?(mask)
+  #
+  # Related: Integer#allbits?, Integer#nobits?.
   #
   def anybits?: (int mask) -> bool
 
   alias arg angle
 
+  # <!--
+  #   rdoc-file=numeric.rb
+  #   - int.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
@@ -247,31 +706,55 @@ class Integer < Numeric
   #
   def bit_length: () -> Integer
 
-  # Returns the smallest number greater than or equal to `int` with a precision of
-  # `ndigits` decimal digits (default: 0).
+  # <!--
+  #   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.
+  # `ndigits.abs` trailing zeros:
+  #
+  #     555.ceil(-1)  # => 560
+  #     555.ceil(-2)  # => 600
+  #     -555.ceil(-2) # => -500
+  #     555.ceil(-3)  # => 1000
   #
   # Returns `self` when `ndigits` is zero or positive.
   #
-  #     1.ceil           #=> 1
-  #     1.ceil(2)        #=> 1
-  #     18.ceil(-1)      #=> 20
-  #     (-18).ceil(-1)   #=> -10
+  #     555.ceil     # => 555
+  #     555.ceil(50) # => 555
+  #
+  # Related: Integer#floor.
   #
   def ceil: () -> Integer
           | (int digits) -> (Integer | Float)
 
-  # Returns a string containing the character represented by the `int`'s value
-  # according to `encoding`.
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - chr           -> string
+  #   - chr(encoding) -> string
+  # -->
+  # Returns a 1-character string containing the character represented by the value
+  # of `self`, according to the given `encoding`.
+  #
+  #     65.chr                   # => "A"
+  #     0..chr                   # => "\x00"
+  #     255.chr                  # => "\xFF"
+  #     string = 255.chr(Encoding::UTF_8)
+  #     string.encoding          # => Encoding::UTF_8
   #
-  #     65.chr    #=> "A"
-  #     230.chr   #=> "\xE6"
-  #     255.chr(Encoding::UTF_8)   #=> "\u00FF"
+  # Raises an exception if `self` is negative.
+  #
+  # Related: Integer#ord.
   #
   def chr: (?encoding) -> String
 
+  # <!--
+  #   rdoc-file=bignum.c
+  #   - big.coerce(numeric)  ->  array
+  # -->
   # Returns an array with both a `numeric` and a `big` represented as Bignum
   # objects.
   #
@@ -281,49 +764,98 @@ class Integer < Numeric
   #
   #     (0x3FFFFFFFFFFFFFFF+1).coerce(42)   #=> [42, 4611686018427387904]
   #
-  def coerce: (Numeric) -> [Numeric, Numeric]
+  def coerce: (Numeric) -> [ Numeric, Numeric ]
 
   def conj: () -> Integer
 
   def conjugate: () -> Integer
 
+  # <!--
+  #   rdoc-file=rational.c
+  #   - int.denominator  ->  1
+  # -->
   # Returns 1.
   #
   def denominator: () -> Integer
 
-  # Returns the digits of `int`'s place-value representation with radix `base`
-  # (default: 10). The digits are returned as an array with the least significant
-  # digit as the first array element.
-  #
-  # `base` must be greater than or equal to 2.
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - digits(base = 10) -> array_of_integers
+  # -->
+  # Returns an array of integers representing the `base`-radix digits of `self`;
+  # the first element of the array represents the least significant digit:
   #
-  #     12345.digits      #=> [5, 4, 3, 2, 1]
-  #     12345.digits(7)   #=> [4, 6, 6, 0, 5]
-  #     12345.digits(100) #=> [45, 23, 1]
+  #     12345.digits      # => [5, 4, 3, 2, 1]
+  #     12345.digits(7)   # => [4, 6, 6, 0, 5]
+  #     12345.digits(100) # => [45, 23, 1]
   #
-  #     -12345.digits(7)  #=> Math::DomainError
+  # Raises an exception if `self` is negative or `base` is less than 2.
   #
   def digits: (?int base) -> ::Array[Integer]
 
-  # Performs integer division: returns the integer result of dividing `int` by
-  # `numeric`.
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - div(numeric)  -> integer
+  # -->
+  # 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
+  #
+  #     Raises an exception if +numeric+ does not have method +div+.
   #
   def div: (Numeric) -> Integer
 
-  # See Numeric#divmod.
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - divmod(other) -> array
+  # -->
+  # Returns a 2-element array `[q, r]`, where
+  #
+  #     q = (self/other).floor    # Quotient
+  #     r = self % other          # Remainder
+  #
+  # Examples:
+  #
+  #     11.divmod(4)              # => [2, 3]
+  #     11.divmod(-4)             # => [-3, -1]
+  #     -11.divmod(4)             # => [-3, 1]
+  #     -11.divmod(-4)            # => [2, -3]
   #
-  def divmod: (Integer) -> [Integer, Integer]
-            | (Float) -> [Float, Float]
-            | (Numeric) -> [Numeric, Numeric]
+  #     12.divmod(4)              # => [3, 0]
+  #     12.divmod(-4)             # => [-3, 0]
+  #     -12.divmod(4)             # => [-3, 0]
+  #     -12.divmod(-4)            # => [3, 0]
+  #
+  #     13.divmod(4.0)            # => [3, 1.0]
+  #     13.divmod(Rational(4, 1)) # => [3, (1/1)]
+  #
+  def divmod: (Integer) -> [ Integer, Integer ]
+            | (Float) -> [ Float, Float ]
+            | (Numeric) -> [ Numeric, Numeric ]
 
-  # Iterates the given block, passing in decreasing values from `int` down to and
-  # including `limit`.
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - downto(limit) {|i| ... } -> self
+  #   - downto(limit)            ->  enumerator
+  # -->
+  # Calls the given block with each integer value from `self` down to `limit`;
+  # returns `self`:
   #
-  # If no block is given, an Enumerator is returned instead.
+  #     a = []
+  #     10.downto(5) {|i| a << i }              # => 10
+  #     a                                       # => [10, 9, 8, 7, 6, 5]
+  #     a = []
+  #     0.downto(-5) {|i| a << i }              # => 0
+  #     a                                       # => [0, -1, -2, -3, -4, -5]
+  #     4.downto(5) {|i| fail 'Cannot happen' } # => 4
   #
-  #     5.downto(1) { |n| print n, ".. " }
-  #     puts "Liftoff!"
-  #     #=> "5.. 4.. 3.. 2.. 1.. Liftoff!"
+  # With no block given, returns an Enumerator.
   #
   def downto: (Integer limit) { (Integer) -> void } -> Integer
             | (Integer limit) -> ::Enumerator[Integer, self]
@@ -332,35 +864,60 @@ class Integer < Numeric
 
   def eql?: (untyped) -> bool
 
+  # <!--
+  #   rdoc-file=numeric.rb
+  #   - int.even?  ->  true or false
+  # -->
   # Returns `true` if `int` is an even number.
   #
   def even?: () -> bool
 
-  # Returns the floating point result of dividing `int` by `numeric`.
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - fdiv(numeric) -> float
+  # -->
+  # Returns the Float result of dividing `self` by `numeric`:
+  #
+  #     4.fdiv(2)      # => 2.0
+  #     4.fdiv(-2)      # => -2.0
+  #     -4.fdiv(2)      # => -2.0
+  #     4.fdiv(2.0)      # => 2.0
+  #     4.fdiv(Rational(3, 4))      # => 5.333333333333333
   #
-  #     654321.fdiv(13731)      #=> 47.652829364212366
-  #     654321.fdiv(13731.24)   #=> 47.65199646936475
-  #     -654321.fdiv(13731)     #=> -47.652829364212366
+  # Raises an exception if `numeric` cannot be converted to a Float.
   #
   def fdiv: (Numeric) -> Float
 
   def finite?: () -> bool
 
-  # Returns the largest number less than or equal to `int` with a precision of
-  # `ndigits` decimal digits (default: 0).
+  # <!--
+  #   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 the precision is negative, the returned value is an integer with at least
-  # `ndigits.abs` trailing zeros.
+  # 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.
   #
-  #     1.floor           #=> 1
-  #     1.floor(2)        #=> 1
-  #     18.floor(-1)      #=> 10
-  #     (-18).floor(-1)   #=> -20
+  #     555.floor     # => 555
+  #     555.floor(50) # => 555
+  #
+  # Related: Integer#ceil.
   #
   def floor: (?int digits) -> Integer
 
+  # <!--
+  #   rdoc-file=rational.c
+  #   - int.gcd(other_int)  ->  integer
+  # -->
   # Returns the greatest common divisor of the two integers. The result is always
   # positive. 0.gcd(x) and x.gcd(0) return x.abs.
   #
@@ -371,6 +928,10 @@ class Integer < Numeric
   #
   def gcd: (Integer) -> Integer
 
+  # <!--
+  #   rdoc-file=rational.c
+  #   - int.gcdlcm(other_int)  ->  array
+  # -->
   # Returns an array with the greatest common divisor and the least common
   # multiple of the two integers, [gcd, lcm].
   #
@@ -389,12 +950,36 @@ class Integer < Numeric
 
   def infinite?: () -> Integer?
 
+  # <!-- rdoc-file=numeric.c -->
+  # Returns a string containing the place-value representation of `self` in radix
+  # `base` (in 2..36).
+  #
+  #     12345.to_s               # => "12345"
+  #     12345.to_s(2)            # => "11000000111001"
+  #     12345.to_s(8)            # => "30071"
+  #     12345.to_s(10)           # => "12345"
+  #     12345.to_s(16)           # => "3039"
+  #     12345.to_s(36)           # => "9ix"
+  #     78546939656932.to_s(36)  # => "rubyrules"
+  #
+  # 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
+  # -->
   # Since `int` is already an Integer, this always returns `true`.
   #
   def integer?: () -> true
 
+  # <!--
+  #   rdoc-file=rational.c
+  #   - int.lcm(other_int)  ->  integer
+  # -->
   # Returns the least common multiple of the two integers. The result is always
   # positive. 0.lcm(x) and x.lcm(0) return zero.
   #
@@ -405,47 +990,100 @@ class Integer < Numeric
   #
   def lcm: (Integer) -> Integer
 
-  # Returns the absolute value of `int`.
-  #
-  #     (-12345).abs   #=> 12345
-  #     -12345.abs     #=> 12345
-  #     12345.abs      #=> 12345
-  #
-  # Integer#magnitude is an alias for Integer#abs.
+  # <!--
+  #   rdoc-file=numeric.rb
+  #   - magnitude()
+  # -->
   #
   def magnitude: () -> Integer
 
-  # Returns `int` modulo `other`.
+  # <!-- rdoc-file=numeric.c -->
+  # Returns `self` modulo `other` as a real number.
+  #
+  # For integer `n` and real number `r`, these expressions are equivalent:
+  #
+  #     n % r
+  #     n-r*(n/r).floor
+  #     n.divmod(r)[1]
+  #
+  # See Numeric#divmod.
+  #
+  # Examples:
+  #
+  #     10 % 2              # => 0
+  #     10 % 3              # => 1
+  #     10 % 4              # => 2
+  #
+  #     10 % -2             # => 0
+  #     10 % -3             # => -2
+  #     10 % -4             # => -2
+  #
+  #     10 % 3.0            # => 1.0
+  #     10 % Rational(3, 1) # => (1/1)
   #
-  # See Numeric#divmod for more information.
+  # Integer#modulo is an alias for Integer#%.
   #
-  alias modulo `%`
+  alias modulo %
 
   def negative?: () -> bool
 
-  # Returns the successor of `int`, i.e. the Integer equal to `int+1`.
+  # <!-- rdoc-file=numeric.c -->
+  # Returns the successor integer of `self` (equivalent to `self + 1`):
   #
-  #     1.next      #=> 2
-  #     (-1).next   #=> 0
-  #     1.succ      #=> 2
-  #     (-1).succ   #=> 0
+  #     1.succ  #=> 2
+  #     -1.succ #=> 0
+  #
+  # Integer#next is an alias for Integer#succ.
+  #
+  # Related: Integer#pred (predecessor value).
   #
   def next: () -> Integer
 
-  # Returns `true` if no bits of `int & mask` are 1.
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - nobits?(mask) -> true or false
+  # -->
+  # Returns `true` if no bit that is set (=1) in `mask` is also set in `self`;
+  # returns `false` otherwise.
+  #
+  # Example values:
+  #
+  #     0b11110000  self
+  #     0b00001111  mask
+  #     0b00000000  self & mask
+  #           true  self.nobits?(mask)
+  #
+  #     0b00000001  self
+  #     0b11111111  mask
+  #     0b00000001  self & mask
+  #          false  self.nobits?(mask)
+  #
+  # Related: Integer#allbits?, Integer#anybits?.
   #
   def nobits?: (int mask) -> bool
 
   def nonzero?: () -> self?
 
+  # <!--
+  #   rdoc-file=rational.c
+  #   - int.numerator  ->  self
+  # -->
   # Returns self.
   #
   def numerator: () -> Integer
 
+  # <!--
+  #   rdoc-file=numeric.rb
+  #   - int.odd?  ->  true or false
+  # -->
   # Returns `true` if `int` is an odd number.
   #
   def odd?: () -> bool
 
+  # <!--
+  #   rdoc-file=numeric.rb
+  #   - int.ord  ->  self
+  # -->
   # Returns the `int` itself.
   #
   #     97.ord   #=> 97
@@ -462,6 +1100,11 @@ class Integer < Numeric
 
   def positive?: () -> bool
 
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - integer.pow(numeric)           ->  numeric
+  #   - integer.pow(integer, integer)  ->  integer
+  # -->
   # Returns (modular) exponentiation as:
   #
   #     a.pow(b)     #=> same as a**b
@@ -472,10 +1115,16 @@ class Integer < Numeric
          | (Rational) -> Rational
          | (Complex) -> Complex
 
-  # Returns the predecessor of `int`, i.e. the Integer equal to `int-1`.
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - pred -> next_integer
+  # -->
+  # Returns the predecessor of `self` (equivalent to `self - 1`):
   #
-  #     1.pred      #=> 0
-  #     (-1).pred   #=> -2
+  #     1.pred  #=> 0
+  #     -1.pred #=> -2
+  #
+  # Related: Integer#succ (successor value).
   #
   def pred: () -> Integer
 
@@ -485,6 +1134,10 @@ class Integer < Numeric
          | (Complex) -> Complex
          | (Numeric) -> Numeric
 
+  # <!--
+  #   rdoc-file=rational.c
+  #   - int.rationalize([eps])  ->  rational
+  # -->
   # Returns the value as a rational.  The optional argument `eps` is always
   # ignored.
   #
@@ -498,51 +1151,87 @@ class Integer < Numeric
 
   alias rectangular rect
 
-  # Returns the remainder after dividing `int` by `numeric`.
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - remainder(other) -> real_number
+  # -->
+  # Returns the remainder after dividing `self` by `other`.
   #
-  # `x.remainder(y)` means `x-y*(x/y).truncate`.
+  # Examples:
   #
-  #     5.remainder(3)     #=> 2
-  #     -5.remainder(3)    #=> -2
-  #     5.remainder(-3)    #=> 2
-  #     -5.remainder(-3)   #=> -2
-  #     5.remainder(1.5)   #=> 0.5
+  #     11.remainder(4)              # => 3
+  #     11.remainder(-4)             # => 3
+  #     -11.remainder(4)             # => -3
+  #     -11.remainder(-4)            # => -3
   #
-  # See Numeric#divmod.
+  #     12.remainder(4)              # => 0
+  #     12.remainder(-4)             # => 0
+  #     -12.remainder(4)             # => 0
+  #     -12.remainder(-4)            # => 0
+  #
+  #     13.remainder(4.0)            # => 1.0
+  #     13.remainder(Rational(4, 1)) # => (1/1)
   #
   def remainder: (Integer) -> Integer
                | (Float) -> Float
                | (Rational) -> Rational
                | (Numeric) -> Numeric
 
-  # Returns `int` rounded to the nearest value with a precision of `ndigits`
-  # decimal digits (default: 0).
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - round(ndigits= 0, half: :up) -> integer
+  # -->
+  # Returns `self` rounded to the nearest value 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.
+  # When `ndigits` is negative, the returned value has at least `ndigits.abs`
+  # trailing zeros:
+  #
+  #     555.round(-1)      # => 560
+  #     555.round(-2)      # => 600
+  #     555.round(-3)      # => 1000
+  #     -555.round(-2)     # => -600
+  #     555.round(-4)      # => 0
   #
   # Returns `self` when `ndigits` is zero or positive.
   #
-  #     1.round           #=> 1
-  #     1.round(2)        #=> 1
-  #     15.round(-1)      #=> 20
-  #     (-15).round(-1)   #=> -20
+  #     555.round     # => 555
+  #     555.round(1)  # => 555
+  #     555.round(50) # => 555
+  #
+  # If keyword argument `half` is given, and `self` is equidistant from the two
+  # candidate  values, the rounding is according to the given `half` value:
   #
-  # The optional `half` keyword argument is available similar to Float#round.
+  # *   `:up` or `nil`: round away from zero:
   #
-  #     25.round(-1, half: :up)      #=> 30
-  #     25.round(-1, half: :down)    #=> 20
-  #     25.round(-1, half: :even)    #=> 20
-  #     35.round(-1, half: :up)      #=> 40
-  #     35.round(-1, half: :down)    #=> 30
-  #     35.round(-1, half: :even)    #=> 40
-  #     (-25).round(-1, half: :up)   #=> -30
-  #     (-25).round(-1, half: :down) #=> -20
-  #     (-25).round(-1, half: :even) #=> -20
+  #         25.round(-1, half: :up)      # => 30
+  #         (-25).round(-1, half: :up)   # => -30
+  #
+  # *   `:down`: round toward zero:
+  #
+  #         25.round(-1, half: :down)    # => 20
+  #         (-25).round(-1, half: :down) # => -20
+  #
+  # *   `:even`: round toward the candidate whose last nonzero digit is even:
+  #
+  #         25.round(-1, half: :even)    # => 20
+  #         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.
   #
   def round: (?half: :up | :down | :even) -> Integer
            | (int digits, ?half: :up | :down | :even) -> (Integer | Float)
 
+  # <!--
+  #   rdoc-file=numeric.rb
+  #   - int.size  ->  int
+  # -->
+  # Document-method: Integer#size
+  #
   # Returns the number of bytes in the machine representation of `int` (machine
   # dependent).
   #
@@ -559,51 +1248,84 @@ class Integer < Numeric
           | (Numeric limit, ?Integer step) { (Integer) -> void } -> void
           | (Numeric limit, ?Numeric step) { (Numeric) -> void } -> void
           | (to: Numeric, ?by: Integer) { (Integer) -> void } -> void
-          | (?to: Numeric, by: Numeric) { (Numeric) -> 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]
-          | (?to: Numeric, by: Numeric) -> Enumerator[Numeric, void]
+          | (by: Numeric, ?to: Numeric) -> Enumerator[Numeric, void]
 
-  # Returns the successor of `int`, i.e. the Integer equal to `int+1`.
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - succ -> next_integer
+  # -->
+  # Returns the successor integer of `self` (equivalent to `self + 1`):
+  #
+  #     1.succ  #=> 2
+  #     -1.succ #=> 0
   #
-  #     1.next      #=> 2
-  #     (-1).next   #=> 0
-  #     1.succ      #=> 2
-  #     (-1).succ   #=> 0
+  # Integer#next is an alias for Integer#succ.
+  #
+  # Related: Integer#pred (predecessor value).
   #
   def succ: () -> Integer
 
-  # Iterates the given block `int` times, passing in values from zero to `int -
-  # 1`.
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - times {|i| ... } -> self
+  #   - times            -> enumerator
+  # -->
+  # Calls the given block `self` times with each integer in `(0..self-1)`:
   #
-  # If no block is given, an Enumerator is returned instead.
+  #     a = []
+  #     5.times {|i| a.push(i) } # => 5
+  #     a                        # => [0, 1, 2, 3, 4]
   #
-  #     5.times {|i| print i, " " }   #=> 0 1 2 3 4
+  # With no block given, returns an Enumerator.
   #
   def times: () { (Integer) -> void } -> self
            | () -> ::Enumerator[Integer, self]
 
   def to_c: () -> Complex
 
-  # Converts `int` to a Float.  If `int` doesn't fit in a Float, the result is
-  # infinity.
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - to_f -> float
+  # -->
+  # Converts `self` to a Float:
+  #
+  #     1.to_f  # => 1.0
+  #     -1.to_f # => -1.0
+  #
+  # If the value of `self` does not fit in a Float, the result is infinity:
+  #
+  #     (10**400).to_f  # => Infinity
+  #     (-10**400).to_f # => -Infinity
   #
   def to_f: () -> Float
 
+  # <!--
+  #   rdoc-file=numeric.rb
+  #   - int.to_i    ->  integer
+  # -->
   # Since `int` is already an Integer, returns `self`.
   #
   # #to_int is an alias for #to_i.
   #
   def to_i: () -> Integer
 
+  # <!--
+  #   rdoc-file=numeric.rb
+  #   - int.to_int  ->  integer
+  # -->
   # Since `int` is already an Integer, returns `self`.
   #
-  # #to_int is an alias for #to_i.
-  #
   alias to_int to_i
 
+  # <!--
+  #   rdoc-file=rational.c
+  #   - int.to_r  ->  rational
+  # -->
   # Returns the value as a rational.
   #
   #     1.to_r        #=> (1/1)
@@ -611,16 +1333,24 @@ class Integer < Numeric
   #
   def to_r: () -> Rational
 
-  # Returns a string containing the place-value representation of `int` with radix
-  # `base` (between 2 and 36).
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - to_s(base = 10)  ->  string
+  # -->
+  # Returns a string containing the place-value representation of `self` in radix
+  # `base` (in 2..36).
   #
-  #     12345.to_s       #=> "12345"
-  #     12345.to_s(2)    #=> "11000000111001"
-  #     12345.to_s(8)    #=> "30071"
-  #     12345.to_s(10)   #=> "12345"
-  #     12345.to_s(16)   #=> "3039"
-  #     12345.to_s(36)   #=> "9ix"
-  #     78546939656932.to_s(36)  #=> "rubyrules"
+  #     12345.to_s               # => "12345"
+  #     12345.to_s(2)            # => "11000000111001"
+  #     12345.to_s(8)            # => "30071"
+  #     12345.to_s(10)           # => "12345"
+  #     12345.to_s(16)           # => "3039"
+  #     12345.to_s(36)           # => "9ix"
+  #     78546939656932.to_s(36)  # => "rubyrules"
+  #
+  # Raises an exception if `base` is out of range.
+  #
+  # Integer#inspect is an alias for Integer#to_s.
   #
   def to_s: () -> String
           | (2) -> String
@@ -660,38 +1390,78 @@ class Integer < Numeric
           | (36) -> String
           | (int base) -> String
 
-  # Returns `int` truncated (toward zero) to a precision of `ndigits` decimal
-  # digits (default: 0).
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - truncate(ndigits = 0) -> integer
+  # -->
+  # Returns `self` truncated (toward zero) to a precision of `ndigits` decimal
+  # digits.
   #
-  # When the precision is negative, the returned value is an integer with at least
-  # `ndigits.abs` trailing zeros.
+  # When `ndigits` is negative, the returned value has at least `ndigits.abs`
+  # trailing zeros:
+  #
+  #     555.truncate(-1)  # => 550
+  #     555.truncate(-2)  # => 500
+  #     -555.truncate(-2) # => -500
   #
   # Returns `self` when `ndigits` is zero or positive.
   #
-  #     1.truncate           #=> 1
-  #     1.truncate(2)        #=> 1
-  #     18.truncate(-1)      #=> 10
-  #     (-18).truncate(-1)   #=> -10
+  #     555.truncate     # => 555
+  #     555.truncate(50) # => 555
+  #
+  # Related: Integer#round.
   #
   def truncate: () -> Integer
               | (int ndigits) -> Integer
 
-  # Iterates the given block, passing in integer values from `int` up to and
-  # including `limit`.
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - upto(limit) {|i| ... } -> self
+  #   - upto(limit)            ->  enumerator
+  # -->
+  # Calls the given block with each integer value from `self` up to `limit`;
+  # returns `self`:
   #
-  # If no block is given, an Enumerator is returned instead.
+  #     a = []
+  #     5.upto(10) {|i| a << i }              # => 5
+  #     a                                     # => [5, 6, 7, 8, 9, 10]
+  #     a = []
+  #     -5.upto(0) {|i| a << i }              # => -5
+  #     a                                     # => [-5, -4, -3, -2, -1, 0]
+  #     5.upto(4) {|i| fail 'Cannot happen' } # => 5
   #
-  #     5.upto(10) {|i| print i, " " }   #=> 5 6 7 8 9 10
+  # With no block given, returns an Enumerator.
   #
   def upto: (Integer limit) { (Integer) -> void } -> Integer
           | (Integer limit) -> ::Enumerator[Integer, self]
 
+  # <!--
+  #   rdoc-file=numeric.rb
+  #   - int.zero? -> true or false
+  # -->
+  # Returns `true` if `int` has a zero value.
+  #
   def zero?: () -> bool
 
-  # Bitwise OR.
+  # <!--
+  #   rdoc-file=numeric.c
+  #   - self | other -> integer
+  # -->
+  # Bitwise OR; each bit in the result is 1 if either corresponding bit in `self`
+  # or `other` is 1, 0 otherwise:
+  #
+  #     "%04b" % (0b0101 | 0b0110) # => "0111"
+  #
+  # Raises an exception if `other` is not an Integer.
+  #
+  # Related: Integer#& (bitwise AND), Integer#^ (bitwise EXCLUSIVE OR).
   #
   def |: (Integer) -> Integer
 
+  # <!--
+  #   rdoc-file=numeric.rb
+  #   - ~int  ->  integer
+  # -->
   # One's complement: returns a number where each bit is flipped.
   #
   # Inverts the bits in an Integer. As integers are conceptually of infinite