Issue #26512: Clarify Integral; tidy up table of rounding functions

Based on patch by Julien.

2 files changed, 20 insertions, 17 deletions

diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 1a1b74c..80f4779 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -361,19 +361,22 @@ Notes:
 All :class:`numbers.Real` types (:class:`int` and :class:`float`) also include
 the following operations:
 
-+--------------------+------------------------------------+--------+
-| Operation          | Result                             | Notes  |
-+====================+====================================+========+
-| ``math.trunc(x)``  | *x* truncated to Integral          |        |
-+--------------------+------------------------------------+--------+
-| ``round(x[, n])``  | *x* rounded to n digits,           |        |
-|                    | rounding half to even. If n is     |        |
-|                    | omitted, it defaults to 0.         |        |
-+--------------------+------------------------------------+--------+
-| ``math.floor(x)``  | the greatest integral float <= *x* |        |
-+--------------------+------------------------------------+--------+
-| ``math.ceil(x)``   | the least integral float >= *x*    |        |
-+--------------------+------------------------------------+--------+
++--------------------+---------------------------------------------+
+| Operation          | Result                                      |
++====================+=============================================+
+| :func:`math.trunc(\| *x* truncated to :class:`~numbers.Integral` |
+| x) <math.trunc>`   |                                             |
++--------------------+---------------------------------------------+
+| :func:`round(x[,   | *x* rounded to *n* digits,                  |
+| n]) <round>`       | rounding half to even. If *n* is            |
+|                    | omitted, it defaults to 0.                  |
++--------------------+---------------------------------------------+
+| :func:`math.floor(\| the greatest :class:`~numbers.Integral`     |
+| x) <math.floor>`   | <= *x*                                      |
++--------------------+---------------------------------------------+
+| :func:`math.ceil(x)| the least :class:`~numbers.Integral` >= *x* |
+| <math.ceil>`       |                                             |
++--------------------+---------------------------------------------+
 
 For additional numeric operations see the :mod:`math` and :mod:`cmath`
 modules.
diff --git a/Modules/mathmodule.c b/Modules/mathmodule.c
index aeb06c5..7ebf8e8 100644
--- a/Modules/mathmodule.c
+++ b/Modules/mathmodule.c
@@ -957,8 +957,8 @@ static PyObject * math_ceil(PyObject *self, PyObject *number) {
 }
 
 PyDoc_STRVAR(math_ceil_doc,
-             "ceil(x)\n\nReturn the ceiling of x as an int.\n"
-             "This is the smallest integral value >= x.");
+             "ceil(x)\n\nReturn the ceiling of x as an Integral.\n"
+             "This is the smallest integer >= x.");
 
 FUNC2(copysign, copysign,
       "copysign(x, y)\n\nReturn a float with the magnitude (absolute value) "
@@ -997,8 +997,8 @@ static PyObject * math_floor(PyObject *self, PyObject *number) {
 }
 
 PyDoc_STRVAR(math_floor_doc,
-             "floor(x)\n\nReturn the floor of x as an int.\n"
-             "This is the largest integral value <= x.");
+             "floor(x)\n\nReturn the floor of x as an Integral.\n"
+             "This is the largest integer <= x.");
 
 FUNC1A(gamma, m_tgamma,
       "gamma(x)\n\nGamma function at x.")