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

3 files changed, 28 insertions, 14 deletions

diff --git a/Doc/library/cmath.rst b/Doc/library/cmath.rst
index c819a66..9d81730 100644
--- 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 0c53b29..9e49463 100644
--- 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 a696af4..163794d 100644
--- 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.)