bpo-29956: Improve the math.exp() related documentation. (#1073)
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 @@
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 @@
.. 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 @@
Constants
---------
-
.. data:: pi
The mathematical constant *π*, as a float.
@@ -253,18 +253,21 @@
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 @@
.. versionadded:: 3.6
+
.. data:: nan
A floating-point "not a number" (NaN) value. Equivalent to
@@ -279,6 +283,7 @@
.. 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 @@
*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 @@
.. 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 @@
Return the square root of *x*.
+
Trigonometric functions
-----------------------
-
.. function:: acos(x)
Return the arc cosine of *x*, in radians.
@@ -339,10 +345,10 @@
Return the tangent of *x* radians.
+
Angular conversion
------------------
-
.. function:: degrees(x)
Convert angle *x* from radians to degrees.
@@ -352,6 +358,7 @@
Convert angle *x* from degrees to radians.
+
Hyperbolic functions
--------------------
@@ -440,23 +447,25 @@
.. 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 @@
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 @@
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.)