bpo-29956: Improve the math.exp() related documentation. (#1073)

diff --git a/Doc/library/cmath.rst b/Doc/library/cmath.rst
index c819a667ec23bf524425cb82202cfca370436b6c..9d81730f20122265e0dd774f6b40ac1073dfb756 100644 (file)
--- a/Doc/library/cmath.rst
+++ b/Doc/library/cmath.rst
@@ -47,7 +47,7 @@ rectangular coordinates to polar coordinates and back.
 
    Return the phase of *x* (also known as the *argument* of *x*), as a
    float.  ``phase(x)`` is equivalent to ``math.atan2(x.imag,
-   x.real)``.  The result lies in the range [-π, π], and the branch
+   x.real)``.  The result lies in the range [-\ *π*, *π*], and the branch
    cut for this operation lies along the negative real axis,
    continuous from above.  On systems with support for signed zeros
    (which includes most systems in current use), this means that the
@@ -86,7 +86,8 @@ Power and logarithmic functions
 
 .. function:: exp(x)
 
-   Return the exponential value ``e**x``.
+   Return *e* raised to the power *x*, where *e* is the base of natural
+   logarithms.
 
 
 .. function:: log(x[, base])
@@ -243,7 +244,6 @@ Classification functions
 Constants
 ---------
 
-
 .. data:: pi
 
    The mathematical constant *π*, as a float.
@@ -253,18 +253,21 @@ Constants
 
    The mathematical constant *e*, as a float.
 
+
 .. data:: tau
 
    The mathematical constant *τ*, as a float.
 
    .. versionadded:: 3.6
 
+
 .. data:: inf
 
    Floating-point positive infinity. Equivalent to ``float('inf')``.
 
    .. versionadded:: 3.6
 
+
 .. data:: infj
 
    Complex number with zero real part and positive infinity imaginary
@@ -272,6 +275,7 @@ Constants
 
    .. versionadded:: 3.6
 
+
 .. data:: nan
 
    A floating-point "not a number" (NaN) value.  Equivalent to
@@ -279,6 +283,7 @@ Constants
 
    .. versionadded:: 3.6
 
+
 .. data:: nanj
 
    Complex number with zero real part and NaN imaginary part. Equivalent to

diff --git a/Doc/library/math.rst b/Doc/library/math.rst
index 0c53b294a9e4b21fa5c7de5e47a8545846f9d02c..9e4946323a9d37ad7c2b070798dec72c8eecd887 100644 (file)
--- a/Doc/library/math.rst
+++ b/Doc/library/math.rst
@@ -42,15 +42,18 @@ Number-theoretic and representation functions
    *y*.  On platforms that support signed zeros, ``copysign(1.0, -0.0)``
    returns *-1.0*.
 
+
 .. function:: fabs(x)
 
    Return the absolute value of *x*.
 
+
 .. function:: factorial(x)
 
    Return *x* factorial.  Raises :exc:`ValueError` if *x* is not integral or
    is negative.
 
+
 .. function:: floor(x)
 
    Return the floor of *x*, the largest integer less than or equal to *x*.
@@ -220,12 +223,15 @@ Power and logarithmic functions
 
 .. function:: exp(x)
 
-   Return e raised to the power *x*, where e = 2.718281... is the base
-   of natural logarithms.
+   Return *e* raised to the power *x*, where *e* = 2.718281... is the base
+   of natural logarithms.  This is usually more accurate than ``math.e ** x``
+   or ``pow(math.e, x)``.
+
 
 .. function:: expm1(x)
 
-   Return ``e**x - 1``.  For small floats *x*, the subtraction in ``exp(x) - 1``
+   Return *e* raised to the power *x*, minus 1.  Here *e* is the base of natural
+   logarithms.  For small floats *x*, the subtraction in ``exp(x) - 1``
    can result in a `significant loss of precision
    <https://en.wikipedia.org/wiki/Loss_of_significance>`_\; the :func:`expm1`
    function provides a way to compute this quantity to full precision::
@@ -290,10 +296,10 @@ Power and logarithmic functions
 
    Return the square root of *x*.
 
+
 Trigonometric functions
 -----------------------
 
-
 .. function:: acos(x)
 
    Return the arc cosine of *x*, in radians.
@@ -339,10 +345,10 @@ Trigonometric functions
 
    Return the tangent of *x* radians.
 
+
 Angular conversion
 ------------------
 
-
 .. function:: degrees(x)
 
    Convert angle *x* from radians to degrees.
@@ -352,6 +358,7 @@ Angular conversion
 
    Convert angle *x* from degrees to radians.
 
+
 Hyperbolic functions
 --------------------
 
@@ -440,23 +447,25 @@ Constants
 
 .. data:: pi
 
-   The mathematical constant π = 3.141592..., to available precision.
+   The mathematical constant *π* = 3.141592..., to available precision.
 
 
 .. data:: e
 
-   The mathematical constant e = 2.718281..., to available precision.
+   The mathematical constant *e* = 2.718281..., to available precision.
+
 
 .. data:: tau
 
-   The mathematical constant τ = 6.283185..., to available precision.
-   Tau is a circle constant equal to 2π, the ratio of a circle's circumference to
+   The mathematical constant *τ* = 6.283185..., to available precision.
+   Tau is a circle constant equal to 2\ *π*, the ratio of a circle's circumference to
    its radius. To learn more about Tau, check out Vi Hart's video `Pi is (still)
    Wrong <https://www.youtube.com/watch?v=jG7vhMMXagQ>`_, and start celebrating
    `Tau day <http://tauday.com/>`_ by eating twice as much pie!
 
    .. versionadded:: 3.6
 
+
 .. data:: inf
 
    A floating-point positive infinity.  (For negative infinity, use

diff --git a/Doc/whatsnew/3.6.rst b/Doc/whatsnew/3.6.rst
index a696af4a999c845b47ebe6fc8ce7281e7361673f..163794da965ec2da4b8087d5413aee0097bc9421 100644 (file)
--- a/Doc/whatsnew/3.6.rst
+++ b/Doc/whatsnew/3.6.rst
@@ -908,7 +908,7 @@ return value.
 cmath
 -----
 
-The new :const:`cmath.tau` (τ) constant has been added.
+The new :const:`cmath.tau` (*τ*) constant has been added.
 (Contributed by Lisa Roach in :issue:`12345`, see :pep:`628` for details.)
 
 New constants: :const:`cmath.inf` and :const:`cmath.nan` to
@@ -1199,7 +1199,7 @@ be reopened.
 math
 ----
 
-The tau (τ) constant has been added to the :mod:`math` and :mod:`cmath`
+The tau (*τ*) constant has been added to the :mod:`math` and :mod:`cmath`
 modules.
 (Contributed by Lisa Roach in :issue:`12345`, see :pep:`628` for details.)