SF bug 996392: math and cmath docs don't specify radians

Major rewrite of the math module docs.  Slapped in "radians" where
appropriate; grouped the functions into reasonable categories; supplied
many more words to address common confusions about some of the subtler
issues.

Doc/lib/libmath.tex

@@ -18,42 +18,13 @@ number used as a parameter, so that the programmer can determine how
 and why it was generated in the first place.
 
 The following functions are provided by this module.  Except
-when explicitly noted otherwise, all return values are floats:
+when explicitly noted otherwise, all return values are floats.
 
-\begin{funcdesc}{acos}{x}
-Return the arc cosine of \var{x}.
-\end{funcdesc}
-
-\begin{funcdesc}{asin}{x}
-Return the arc sine of \var{x}.
-\end{funcdesc}
-
-\begin{funcdesc}{atan}{x}
-Return the arc tangent of \var{x}.
-\end{funcdesc}
-
-\begin{funcdesc}{atan2}{y, x}
-Return \code{atan(\var{y} / \var{x})}.
-\end{funcdesc}
+Number-theoretic and representation functions:
 
 \begin{funcdesc}{ceil}{x}
-Return the ceiling of \var{x} as a float.
-\end{funcdesc}
-
-\begin{funcdesc}{cos}{x}
-Return the cosine of \var{x}.
-\end{funcdesc}
-
-\begin{funcdesc}{cosh}{x}
-Return the hyperbolic cosine of \var{x}.
-\end{funcdesc}
-
-\begin{funcdesc}{degrees}{x}
-Converts angle \var{x} from radians to degrees.
-\end{funcdesc}
-
-\begin{funcdesc}{exp}{x}
-Return \code{e**\var{x}}.
+Return the ceiling of \var{x} as a float, the smallest integer value
+greater than or equal to \var{x}.
 \end{funcdesc}
 
 \begin{funcdesc}{fabs}{x}
@@ -61,35 +32,63 @@ Return the absolute value of \var{x}.
 \end{funcdesc}
 
 \begin{funcdesc}{floor}{x}
-Return the floor of \var{x} as a float.
+Return the floor of \var{x} as a float, the largest integer value
+less than or equal to \var{x}.
 \end{funcdesc}
 
 \begin{funcdesc}{fmod}{x, y}
 Return \code{fmod(\var{x}, \var{y})}, as defined by the platform C library.
 Note that the Python expression \code{\var{x} \%\ \var{y}} may not return
-the same result.
+the same result.  The intent of the C standard is that
+\code{fmod(\var{x}, \var{y})} be exactly (mathematically; to infinite
+precision) equal to \code{\var{x} - \var{n}*\var{y}} for some integer
+\var{n} such that the result has the same sign as \var{x} and
+magnitude less than \code{abs(\var{y})}.  Python's
+\code{\var{x} \%\ \var{y}} returns a result with the sign of
+\var{y} instead, and may not be exactly computable for float arguments.
+For example, \code{fmod(-1e-100, 1e100)} is \code{-1e-100}, but the
+result of Python's \code{-1e-100 \%\ 1e100} is \code{1e100-1e-100}, which
+cannot be represented exactly as a float, and rounds to the surprising
+\code{1e100}.  For this reason, function \function{fmod()} is generally
+preferred when working with floats, while Python's
+\code{\var{x} \%\ \var{y}} is preferred when working with integers.
 \end{funcdesc}
 
 \begin{funcdesc}{frexp}{x}
-% Blessed by Tim.
 Return the mantissa and exponent of \var{x} as the pair
 \code{(\var{m}, \var{e})}.  \var{m} is a float and \var{e} is an
-integer such that \code{\var{x} == \var{m} * 2**\var{e}}.
+integer such that \code{\var{x} == \var{m} * 2**\var{e}} exactly.
 If \var{x} is zero, returns \code{(0.0, 0)}, otherwise
-\code{0.5 <= abs(\var{m}) < 1}.
+\code{0.5 <= abs(\var{m}) < 1}.  This is used to "pick apart" the
+internal representation of a float in a portable way.
 \end{funcdesc}
 
-\begin{funcdesc}{hypot}{x, y}
-Return the Euclidean distance, \code{sqrt(\var{x}*\var{x} + \var{y}*\var{y})}.
+\begin{funcdesc}{ldexp}{x, i}
+Return \code{\var{x} * (2**\var{i})}.  This is essentially the inverse of
+function \function{frexp()}.
 \end{funcdesc}
 
-\begin{funcdesc}{ldexp}{x, i}
-Return \code{\var{x} * (2**\var{i})}.
+\begin{funcdesc}{modf}{x}
+Return the fractional and integer parts of \var{x}.  Both results
+carry the sign of \var{x}, and both are floats.
+\end{funcdesc}
+
+Note that \function{frexp()} and \function{modf()} have a different
+call/return pattern than their C equivalents: they take a single
+argument and return a pair of values, rather than returning their
+second return value through an `output parameter' (there is no such
+thing in Python).
+
+Power and logarithmic functions:
+
+\begin{funcdesc}{exp}{x}
+Return \code{e**\var{x}}.
 \end{funcdesc}
 
 \begin{funcdesc}{log}{x\optional{, base}}
-Returns the logarithm of \var{x} to the given \var{base}.
-If the \var{base} is not specified, returns the natural logarithm of \var{x}.
+Return the logarithm of \var{x} to the given \var{base}.
+If the \var{base} is not specified, return the natural logarithm of \var{x}
+(that is, the logarithm to base \emph{e}).
 \versionchanged[\var{base} argument added]{2.3}
 \end{funcdesc}
 
@@ -97,45 +96,81 @@ If the \var{base} is not specified, returns the natural logarithm of \var{x}.
 Return the base-10 logarithm of \var{x}.
 \end{funcdesc}
 
-\begin{funcdesc}{modf}{x}
-Return the fractional and integer parts of \var{x}.  Both results
-carry the sign of \var{x}.  The integer part is returned as a float.
-\end{funcdesc}
-
 \begin{funcdesc}{pow}{x, y}
 Return \code{\var{x}**\var{y}}.
 \end{funcdesc}
 
-\begin{funcdesc}{radians}{x}
-Converts angle \var{x} from degrees to radians.
+\begin{funcdesc}{sqrt}{x}
+Return the square root of \var{x}.
 \end{funcdesc}
 
-\begin{funcdesc}{sin}{x}
-Return the sine of \var{x}.
+Trigonometric functions:
+
+\begin{funcdesc}{acos}{x}
+Return the arc cosine of \var{x}, in radians.
 \end{funcdesc}
 
-\begin{funcdesc}{sinh}{x}
-Return the hyperbolic sine of \var{x}.
+\begin{funcdesc}{asin}{x}
+Return the arc sine of \var{x}, in radians.
 \end{funcdesc}
 
-\begin{funcdesc}{sqrt}{x}
-Return the square root of \var{x}.
+\begin{funcdesc}{atan}{x}
+Return the arc tangent of \var{x}, in radians.
+\end{funcdesc}
+
+\begin{funcdesc}{atan2}{y, x}
+Return \code{atan(\var{y} / \var{x})}, in radians.
+The result is between \code{-pi} and \code{pi}.
+The vector in the plane from the origin to point \code{(\var{x}, \var{y})}
+makes this angle with the positive X axis.
+The point of \function{atan2()} is that the signs of both inputs are
+known to it, so it can compute the correct quadrant for the angle.
+For example, \code{atan(1}) and \code{atan2(1, 1)} are both \code{pi/4},
+but \code{atan2(-1, -1)} is \code{-3*pi/4}.
+\end{funcdesc}
+
+\begin{funcdesc}{cos}{x}
+Return the cosine of \var{x} radians.
+\end{funcdesc}
+
+\begin{funcdesc}{hypot}{x, y}
+Return the Euclidean norm, \code{sqrt(\var{x}*\var{x} + \var{y}*\var{y})}.
+This is the length of the vector from the origin to point
+\code{(\var{x}, \var{y})}.
+\end{funcdesc}
+
+\begin{funcdesc}{sin}{x}
+Return the sine of \var{x} radians.
 \end{funcdesc}
 
 \begin{funcdesc}{tan}{x}
-Return the tangent of \var{x}.
+Return the tangent of \var{x} radians.
+\end{funcdesc}
+
+Angular conversion:
+
+\begin{funcdesc}{degrees}{x}
+Converts angle \var{x} from radians to degrees.
+\end{funcdesc}
+
+\begin{funcdesc}{radians}{x}
+Converts angle \var{x} from degrees to radians.
+\end{funcdesc}
+
+Hyerbolic functions:
+
+\begin{funcdesc}{cosh}{x}
+Return the hyperbolic cosine of \var{x}.
+\end{funcdesc}
+
+\begin{funcdesc}{sinh}{x}
+Return the hyperbolic sine of \var{x}.
 \end{funcdesc}
 
 \begin{funcdesc}{tanh}{x}
 Return the hyperbolic tangent of \var{x}.
 \end{funcdesc}
 
-Note that \function{frexp()} and \function{modf()} have a different
-call/return pattern than their C equivalents: they take a single
-argument and return a pair of values, rather than returning their
-second return value through an `output parameter' (there is no such
-thing in Python).
-
 The module also defines two mathematical constants:
 
 \begin{datadesc}{pi}

Misc/NEWS

@@ -139,7 +139,7 @@ C API
 Documentation
 -------------
 
-Improved the tutorial on creating types in C.
+- Improved the tutorial on creating types in C.
 
   - point out the importance of reassigning data members before
     assigning thier values
@@ -148,6 +148,7 @@ Improved the tutorial on creating types in C.
 
   - mention the labor saving Py_VISIT and Py_CLEAR macros.
 
+- Major rewrite of the math module docs, to address common confusions.
 
 New platforms
 -------------