Index: Doc/library/cmath.rst
===================================================================
 Doc/library/cmath.rst (revision 74184)
+++ Doc/library/cmath.rst (working copy)
@@ 23,102 +23,114 @@
support signed zeros the continuity is as specified below.
Complex coordinates

+Conversions to and from polar coordinates
+
Complex numbers can be expressed by two important coordinate systems.
Python's :class:`complex` type uses rectangular coordinates where a number
on the complex plane is defined by two floats, the real part and the imaginary
part.
+A Python complex number ``z`` is stored internally using *rectangular*
+or *Cartesian* coordinates. It is completely determined by its *real
+part* ``z.real`` and its *imaginary part* ``z.imag``. In other
+words::
Definition::
+ z == z.real + z.imag*1j
 z = x + 1j * y
+*Polar coordinates* give an alternative way to represent a complex
+number. In polar coordinates, a complex number *z* is defined by the
+modulus *r* and the phase angle *phi*. The modulus *r* is the distance
+from *z* to the origin, while the phase *phi* is the counterclockwise
+angle from the positive xaxis to the line segment that joins the
+origin to *z*.
 x := z.real
 y := z.imag
+The following functions can be used to convert from the native
+rectangular coordinates to polar coordinates and back.
In engineering the polar coordinate system is popular for complex numbers. In
polar coordinates a complex number is defined by the radius *r* and the phase
angle *phi*. The radius *r* is the absolute value of the complex, which can be
viewed as distance from (0, 0). The radius *r* is always 0 or a positive float.
The phase angle *phi* is the counter clockwise angle from the positive x axis,
e.g. *1* has the angle *0*, *1j* has the angle *π/2* and *1* the angle *π*.
+.. function:: phase(x)
.. note::
 While :func:`phase` and func:`polar` return *+π* for a negative real they
 may return *π* for a complex with a very small negative imaginary
 part, e.g. *11E300j*.
+ 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
+ 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
+ sign of the result is the same as the sign of ``x.imag``, even when
+ ``x.imag`` is zero::
+ >>> phase(complex(1.0, 0.0))
+ 3.1415926535897931
+ >>> phase(complex(1.0, 0.0))
+ 3.1415926535897931
Definition::
+ .. versionadded:: 2.6
 z = r * exp(1j * phi)
 z = r * cis(phi)
 r := abs(z) := sqrt(real(z)**2 + imag(z)**2)
 phi := phase(z) := atan2(imag(z), real(z))
 cis(phi) := cos(phi) + 1j * sin(phi)
+.. note::
+ The modulus (absolute value) of a complex number *x* can be
+ computed using the builtin :func:`abs` function. There is no
+ separate :mod:`cmath` module function for this operation.
.. function:: phase(x)
 Return phase, also known as the argument, of a complex.
+.. function:: polar(x)
+ Return the representation of *x* in polar coordinates. Returns a
+ pair ``(r, phi)`` where *r* is the modulus of *x* and phi is the
+ phase of *x*. ``polar(x)`` is equivalent to ``(abs(x),
+ phase(x))``.
+
.. versionadded:: 2.6
.. function:: polar(x)
+.. function:: rect(r, phi)
 Convert a :class:`complex` from rectangular coordinates to polar
 coordinates. The function returns a tuple with the two elements
 *r* and *phi*. *r* is the distance from 0 and *phi* the phase
 angle.
+ Return the complex number *x* with polar coordinates *r* and *phi*.
+ Equivalent to ``r * (math.cos(phi) + math.sin(phi)*1j)``.
.. versionadded:: 2.6
.. function:: rect(r, phi)
+Power and logarithmic functions
+
 Convert from polar coordinates to rectangular coordinates and return
 a :class:`complex`.
+.. function:: exp(x)
 .. versionadded:: 2.6
+ Return the exponential value ``e**x``.
+.. function:: log(x[, base])
cmath functions

+ Returns the logarithm of *x* to the given *base*. If the *base* is not
+ specified, returns the natural logarithm of *x*. There is one branch cut, from 0
+ along the negative real axis to ∞, continuous from above.
.. function:: acos(x)
+ .. versionchanged:: 2.4
+ *base* argument added.
 Return the arc cosine of *x*. There are two branch cuts: One extends right from
 1 along the real axis to ∞, continuous from below. The other extends left from
 1 along the real axis to ∞, continuous from above.
+.. function:: log10(x)
.. function:: acosh(x)
+ Return the base10 logarithm of *x*. This has the same branch cut as
+ :func:`log`.
 Return the hyperbolic arc cosine of *x*. There is one branch cut, extending left
 from 1 along the real axis to ∞, continuous from above.
+.. function:: sqrt(x)
.. function:: asin(x)
+ Return the square root of *x*. This has the same branch cut as :func:`log`.
 Return the arc sine of *x*. This has the same branch cuts as :func:`acos`.
+Trigonometric functions
+
.. function:: asinh(x)
+.. function:: acos(x)
 Return the hyperbolic arc sine of *x*. There are two branch cuts:
 One extends from ``1j`` along the imaginary axis to ``∞j``,
 continuous from the right. The other extends from ``1j`` along
 the imaginary axis to ``∞j``, continuous from the left.
+ Return the arc cosine of *x*. There are two branch cuts: One extends right from
+ 1 along the real axis to ∞, continuous from below. The other extends left from
+ 1 along the real axis to ∞, continuous from above.
 .. versionchanged:: 2.6
 branch cuts moved to match those recommended by the C99 standard
+.. function:: asin(x)
+ Return the arc sine of *x*. This has the same branch cuts as :func:`acos`.
+
+
.. function:: atan(x)
Return the arc tangent of *x*. There are two branch cuts: One extends from
@@ 130,90 +142,89 @@
direction of continuity of upper cut reversed
.. function:: atanh(x)

 Return the hyperbolic arc tangent of *x*. There are two branch cuts: One
 extends from ``1`` along the real axis to ``∞``, continuous from below. The
 other extends from ``1`` along the real axis to ``∞``, continuous from
 above.

 .. versionchanged:: 2.6
 direction of continuity of right cut reversed


.. function:: cos(x)
Return the cosine of *x*.
.. function:: cosh(x)
+.. function:: sin(x)
 Return the hyperbolic cosine of *x*.
+ Return the sine of *x*.
.. function:: exp(x)
+.. function:: tan(x)
 Return the exponential value ``e**x``.
+ Return the tangent of *x*.
.. function:: isinf(x)
+Hyperbolic functions
+
 Return *True* if the real or the imaginary part of x is positive
 or negative infinity.
+.. function:: acosh(x)
 .. versionadded:: 2.6
+ Return the hyperbolic arc cosine of *x*. There is one branch cut, extending left
+ from 1 along the real axis to ∞, continuous from above.
.. function:: isnan(x)
+.. function:: asinh(x)
 Return *True* if the real or imaginary part of x is not a number (NaN).
+ Return the hyperbolic arc sine of *x*. There are two branch cuts:
+ One extends from ``1j`` along the imaginary axis to ``∞j``,
+ continuous from the right. The other extends from ``1j`` along
+ the imaginary axis to ``∞j``, continuous from the left.
 .. versionadded:: 2.6
+ .. versionchanged:: 2.6
+ branch cuts moved to match those recommended by the C99 standard
.. function:: log(x[, base])
+.. function:: atanh(x)
 Returns the logarithm of *x* to the given *base*. If the *base* is not
 specified, returns the natural logarithm of *x*. There is one branch cut, from 0
 along the negative real axis to ∞, continuous from above.
+ Return the hyperbolic arc tangent of *x*. There are two branch cuts: One
+ extends from ``1`` along the real axis to ``∞``, continuous from below. The
+ other extends from ``1`` along the real axis to ``∞``, continuous from
+ above.
 .. versionchanged:: 2.4
 *base* argument added.
+ .. versionchanged:: 2.6
+ direction of continuity of right cut reversed
.. function:: log10(x)
+.. function:: cosh(x)
 Return the base10 logarithm of *x*. This has the same branch cut as
 :func:`log`.
+ Return the hyperbolic cosine of *x*.
.. function:: sin(x)
+.. function:: sinh(x)
 Return the sine of *x*.
+ Return the hyperbolic sine of *x*.
.. function:: sinh(x)
+.. function:: tanh(x)
 Return the hyperbolic sine of *x*.
+ Return the hyperbolic tangent of *x*.
.. function:: sqrt(x)
+Classification functions
+
 Return the square root of *x*. This has the same branch cut as :func:`log`.
+.. function:: isinf(x)
+ Return *True* if the real or the imaginary part of x is positive
+ or negative infinity.
.. function:: tan(x)
+ .. versionadded:: 2.6
 Return the tangent of *x*.
+.. function:: isnan(x)
.. function:: tanh(x)
+ Return *True* if the real or imaginary part of x is not a number (NaN).
 Return the hyperbolic tangent of *x*.
+ .. versionadded:: 2.6
The module also defines two mathematical constants:
+Constants
+
+
.. data:: pi
The mathematical constant *π*, as a float.