Close #16036: Backport 3.x documentation improvement.

See changeset 6ccb04c4cbae for the corresponding 3.3 change.

Doc/library/functions.rst

@@ -623,20 +623,26 @@ available.  They are listed here in alphabetical order.
    Consider using the :func:`raw_input` function for general input from users.
 
 
-.. function:: int([x[, base]])
+.. function:: int(x=0)
+              int(x, base=10)
 
-   Convert a string or number to a plain integer.  If the argument is a string,
+   Convert a number or string *x* to an integer, or return ``0`` if no
-   it must contain a possibly signed decimal number representable as a Python
+   arguments are given.  If *x* is a number, it can be a plain integer, a long
-   integer, possibly embedded in whitespace.  The *base* parameter gives the
+   integer, or a floating point number.  If *x* is floating point, the conversion
-   base for the conversion (which is 10 by default) and may be any integer in
+   truncates towards zero.  If the argument is outside the integer range, the
-   the range [2, 36], or zero.  If *base* is zero, the proper radix is
+   function returns a long object instead.
-   determined based on the contents of string; the interpretation is the same as
+
-   for integer literals.  (See :ref:`numbers`.)  If *base* is specified and *x*
+   If *x* is not a number or if *base* is given, then *x* must be a string or
-   is not a string, :exc:`TypeError` is raised. Otherwise, the argument may be a
+   Unicode object representing an :ref:`integer literal <integers>` in radix
-   plain or long integer or a floating point number.  Conversion of floating
+   *base*.  Optionally, the literal can be
-   point numbers to integers truncates (towards zero).  If the argument is
+   preceded by ``+`` or ``-`` (with no space in between) and surrounded by
-   outside the integer range a long object will be returned instead.  If no
+   whitespace.  A base-n literal consists of the digits 0 to n-1, with ``a``
-   arguments are given, returns ``0``.
+   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``/``0``, or ``0x``/``0X``, as with integer literals in code.
+   Base 0 means to interpret the string exactly as an integer literal, so that
+   the actual base is 2, 8, 10, or 16.
 
    The integer type is described in :ref:`typesnumeric`.
 

Misc/NEWS

@@ -459,6 +459,9 @@ Build
 Documentation
 -------------
 
+- Issue #16036: Improve documentation of built-in int()'s signature and
+  arguments.
+
 - Issue #15935: Clarification of argparse docs, re: add_argument() type and
   default arguments.  Patch contributed by Chris Jerdonek.