gh-100428: Make int documentation more accurate (GH-100436)

- Remove first link to lexical definition of integer literal, since it
  doesn't apply (differs in handling of leading zeros, base needs to be
  explicitly specified, unicode digits are allowed)
- Better describe handling of leading zeros, unicode digits, underscores
- Base 0 does not work exactly as like a code literal, since it allows
  Unicode digits. Link code literal to lexical definition of integer
  literal.
(cherry picked from commit edfbf56f4ca6588dfd20b53f534a4465e43c82bd)

Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>

diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index e9e3177a99c79a46e0e46ba6396b9e6223f87a67..2afd72f3cddcc769b44706effe12262829012314 100644 (file)
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -892,17 +892,21 @@ are always available.  They are listed here in alphabetical order.
    For floating point numbers, this truncates towards zero.
 
    If *x* is not a number or if *base* is given, then *x* must be a string,
-   :class:`bytes`, or :class:`bytearray` instance representing an :ref:`integer
-   literal <integers>` in radix *base*.  Optionally, the literal can be
-   preceded by ``+`` or ``-`` (with no space in between) and surrounded by
-   whitespace.  A base-n literal consists of the digits 0 to n-1, with ``a``
-   to ``z`` (or ``A`` to ``Z``) having
-   values 10 to 35.  The default *base* is 10. The allowed values are 0 and 2--36.
-   Base-2, -8, and -16 literals can be optionally prefixed with ``0b``/``0B``,
-   ``0o``/``0O``, or ``0x``/``0X``, as with integer literals in code.  Base 0
-   means to interpret exactly as a code literal, so that the actual base is 2,
-   8, 10, or 16, and so that ``int('010', 0)`` is not legal, while
-   ``int('010')`` is, as well as ``int('010', 8)``.
+   :class:`bytes`, or :class:`bytearray` instance representing an integer
+   in radix *base*.  Optionally, the string can be preceded by ``+`` or ``-``
+   (with no space in between), have leading zeros, be surrounded by whitespace,
+   and have single underscores interspersed between digits.
+
+   A base-n integer string contains digits, each representing a value from 0 to
+   n-1. The values 0--9 can be represented by any Unicode decimal digit. The
+   values 10--35 can be represented by ``a`` to ``z`` (or ``A`` to ``Z``). The
+   default *base* is 10. The allowed bases are 0 and 2--36. Base-2, -8, and -16
+   strings can be optionally prefixed with ``0b``/``0B``, ``0o``/``0O``, or
+   ``0x``/``0X``, as with integer literals in code.  For base 0, the string is
+   interpreted in a similar way to an :ref:`integer literal in code <integers>`,
+   in that the actual base is 2, 8, 10, or 16 as determined by the prefix. Base
+   0 also disallows leading zeros: ``int('010', 0)`` is not legal, while
+   ``int('010')`` and ``int('010', 8)`` are.
 
    The integer type is described in :ref:`typesnumeric`.