bpo-26701: Improve documentation for the rounding special methods. (#6054)

diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 26ad7b8c050c2f968b78e984fc7594e0d9583260..1e93ef4594a93441acb06bac8245703183a78cc2 100644 (file)
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -2364,28 +2364,17 @@ left undefined.
 .. method:: object.__complex__(self)
             object.__int__(self)
             object.__float__(self)
-            object.__round__(self, [,n])
 
    .. index::
       builtin: complex
       builtin: int
       builtin: float
-      builtin: round
 
    Called to implement the built-in functions :func:`complex`,
-   :func:`int`, :func:`float` and :func:`round`.  Should return a value
+   :func:`int` and :func:`float`.  Should return a value
    of the appropriate type.
 
 
-.. method:: object.__trunc__(self)
-
-   Called to implement :meth:`math.trunc`.  Should return the value of the
-   object truncated to a :class:`numbers.Integral` (typically an
-   :class:`int`).  If a class defines :meth:`__trunc__` but not
-   :meth:`__int__`, then :meth:`__trunc__` is called to implement the
-   built-in function :func:`int`.
-
-
 .. method:: object.__index__(self)
 
    Called to implement :func:`operator.index`, and whenever Python needs to
@@ -2401,6 +2390,23 @@ left undefined.
       the same value.
 
 
+.. method:: object.__round__(self, [,ndigits])
+            object.__trunc__(self)
+            object.__floor__(self)
+            object.__ceil__(self)
+
+   .. index:: builtin: round
+
+   Called to implement the built-in function :func:`round` and :mod:`math`
+   functions :func:`~math.trunc`, :func:`~math.floor` and :func:`~math.ceil`.
+   Unless *ndigits* is passed to :meth:`!__round__` all these methods should
+   return the value of the object truncated to an :class:`~numbers.Integral`
+   (typically an :class:`int`).
+
+   If :meth:`__int__` is not defined then the built-in function :func:`int`
+   falls back to :meth:`__trunc__`.
+
+
 .. _context-managers:
 
 With Statement Context Managers