DOC: Document ldexp and frexp.

The documentation needs to be in umathmodule.c as that is where ldexp
and frexp and defined. I moved the current documention from
add_newdocs.py to ufunc_docstrings.py, manually translated them into C
strings, and inserted them into umathmodule.c.

Closes #2354.

3 files changed, 184 insertions, 83 deletions

diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py
index 6934cadcc..30d5a68ea 100644
--- a/numpy/add_newdocs.py
+++ b/numpy/add_newdocs.py
@@ -4693,45 +4693,6 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('view',
 #
 ##############################################################################
 
-add_newdoc('numpy.core.umath', 'frexp',
-    """
-    Return normalized fraction and exponent of 2 of input array, element-wise.
-
-    Returns (`out1`, `out2`) from equation ``x` = out1 * 2**out2``.
-
-    Parameters
-    ----------
-    x : array_like
-        Input array.
-
-    Returns
-    -------
-    (out1, out2) : tuple of ndarrays, (float, int)
-        `out1` is a float array with values between -1 and 1.
-        `out2` is an int array which represent the exponent of 2.
-
-    See Also
-    --------
-    ldexp : Compute ``y = x1 * 2**x2``, the inverse of `frexp`.
-
-    Notes
-    -----
-    Complex dtypes are not supported, they will raise a TypeError.
-
-    Examples
-    --------
-    >>> x = np.arange(9)
-    >>> y1, y2 = np.frexp(x)
-    >>> y1
-    array([ 0.   ,  0.5  ,  0.5  ,  0.75 ,  0.5  ,  0.625,  0.75 ,  0.875,
-            0.5  ])
-    >>> y2
-    array([0, 1, 2, 2, 3, 3, 3, 3, 4])
-    >>> y1 * 2**y2
-    array([ 0.,  1.,  2.,  3.,  4.,  5.,  6.,  7.,  8.])
-
-    """)
-
 add_newdoc('numpy.core.umath', 'frompyfunc',
     """
     frompyfunc(func, nin, nout)
@@ -4772,44 +4733,6 @@ add_newdoc('numpy.core.umath', 'frompyfunc',
 
     """)
 
-add_newdoc('numpy.core.umath', 'ldexp',
-    """
-    Compute y = x1 * 2**x2.
-
-    Parameters
-    ----------
-    x1 : array_like
-        The array of multipliers.
-    x2 : array_like
-        The array of exponents.
-
-    Returns
-    -------
-    y : array_like
-        The output array, the result of ``x1 * 2**x2``.
-
-    See Also
-    --------
-    frexp : Return (y1, y2) from ``x = y1 * 2**y2``, the inverse of `ldexp`.
-
-    Notes
-    -----
-    Complex dtypes are not supported, they will raise a TypeError.
-
-    `ldexp` is useful as the inverse of `frexp`, if used by itself it is
-    more clear to simply use the expression ``x1 * 2**x2``.
-
-    Examples
-    --------
-    >>> np.ldexp(5, np.arange(4))
-    array([  5.,  10.,  20.,  40.], dtype=float32)
-
-    >>> x = np.arange(6)
-    >>> np.ldexp(*np.frexp(x))
-    array([ 0.,  1.,  2.,  3.,  4.,  5.])
-
-    """)
-
 add_newdoc('numpy.core.umath', 'geterrobj',
     """
     geterrobj()
diff --git a/numpy/core/code_generators/ufunc_docstrings.py b/numpy/core/code_generators/ufunc_docstrings.py
index 24bccc4d4..4d302969e 100644
--- a/numpy/core/code_generators/ufunc_docstrings.py
+++ b/numpy/core/code_generators/ufunc_docstrings.py
@@ -3323,3 +3323,97 @@ add_newdoc('numpy.core.umath', 'true_divide',
     array([0, 0, 0, 0, 1])
 
     """)
+
+# This doc is not currently used, but has been converted to a C string
+# that can be found in numpy/core/src/umath/umathmodule.c where the
+# frexp ufunc is constructed.
+add_newdoc('numpy.core.umath', 'frexp',
+    """
+    Decompose the elements of x into mantissa and twos exponent.
+
+    Returns (`mantissa`, `exponent`), where `x = mantissa * 2**exponent``.
+    The mantissa is lies in the open interval(-1, 1), while the twos
+    exponent is a signed integer.
+
+    Parameters
+    ----------
+    x : array_like
+        Array of numbers to be decomposed.
+    out1: ndarray, optional
+        Output array for the mantissa. Must have the same shape as `x`.
+    out2: ndarray, optional
+        Output array for the exponent. Must have the same shape as `x`.
+
+    Returns
+    -------
+    (mantissa, exponent) : tuple of ndarrays, (float, int)
+        `mantissa` is a float array with values between -1 and 1.
+        `exponent` is an int array which represents the exponent of 2.
+
+    See Also
+    --------
+    ldexp : Compute ``y = x1 * 2**x2``, the inverse of `frexp`.
+
+    Notes
+    -----
+    Complex dtypes are not supported, they will raise a TypeError.
+
+    Examples
+    --------
+    >>> x = np.arange(9)
+    >>> y1, y2 = np.frexp(x)
+    >>> y1
+    array([ 0.   ,  0.5  ,  0.5  ,  0.75 ,  0.5  ,  0.625,  0.75 ,  0.875,
+            0.5  ])
+    >>> y2
+    array([0, 1, 2, 2, 3, 3, 3, 3, 4])
+    >>> y1 * 2**y2
+    array([ 0.,  1.,  2.,  3.,  4.,  5.,  6.,  7.,  8.])
+
+    """)
+
+# This doc is not currently used, but has been converted to a C string
+# that can be found in numpy/core/src/umath/umathmodule.c where the
+# ldexp ufunc is constructed.
+add_newdoc('numpy.core.umath', 'ldexp',
+    """
+    Returns x1 * 2**x2, element-wise.
+
+    The mantissas `x1` and twos exponents `x2` are used to construct
+    floating point numbers ``x1 * 2**x2``.
+
+    Parameters
+    ----------
+    x1 : array_like
+        Array of multipliers.
+    x2 : array_like, int
+        Array of twos exponents.
+    out : ndarray, optional
+        Output array for the result.
+
+    Returns
+    -------
+    y : ndarray or scalar
+        The result of ``x1 * 2**x2``.
+
+    See Also
+    --------
+    frexp : Return (y1, y2) from ``x = y1 * 2**y2``, inverse to `ldexp`.
+
+    Notes
+    -----
+    Complex dtypes are not supported, they will raise a TypeError.
+
+    `ldexp` is useful as the inverse of `frexp`, if used by itself it is
+    more clear to simply use the expression ``x1 * 2**x2``.
+
+    Examples
+    --------
+    >>> np.ldexp(5, np.arange(4))
+    array([  5.,  10.,  20.,  40.], dtype=float32)
+
+    >>> x = np.arange(6)
+    >>> np.ldexp(*np.frexp(x))
+    array([ 0.,  1.,  2.,  3.,  4.,  5.])
+
+    """)
diff --git a/numpy/core/src/umath/umathmodule.c b/numpy/core/src/umath/umathmodule.c
index f395d5096..b1fc2f7be 100644
--- a/numpy/core/src/umath/umathmodule.c
+++ b/numpy/core/src/umath/umathmodule.c
@@ -251,6 +251,50 @@ static PyUFuncGenericFunction ldexp_functions[] = {
 #endif
 };
 
+static const char frdoc[] =
+    "    Decompose the elements of x into mantissa and twos exponent.\n"
+    "\n"
+    "    Returns (`mantissa`, `exponent`), where `x = mantissa * 2**exponent``.\n"
+    "    The mantissa is lies in the open interval(-1, 1), while the twos\n"
+    "    exponent is a signed integer.\n"
+    "\n"
+    "    Parameters\n"
+    "    ----------\n"
+    "    x : array_like\n"
+    "        Array of numbers to be decomposed.\n"
+    "    out1: ndarray, optional\n"
+    "        Output array for the mantissa. Must have the same shape as `x`.\n"
+    "    out2: ndarray, optional\n"
+    "        Output array for the exponent. Must have the same shape as `x`.\n"
+    "\n"
+    "    Returns\n"
+    "    -------\n"
+    "    (mantissa, exponent) : tuple of ndarrays, (float, int)\n"
+    "        `mantissa` is a float array with values between -1 and 1.\n"
+    "        `exponent` is an int array which represents the exponent of 2.\n"
+    "\n"
+    "    See Also\n"
+    "    --------\n"
+    "    ldexp : Compute ``y = x1 * 2**x2``, the inverse of `frexp`.\n"
+    "\n"
+    "    Notes\n"
+    "    -----\n"
+    "    Complex dtypes are not supported, they will raise a TypeError.\n"
+    "\n"
+    "    Examples\n"
+    "    --------\n"
+    "    >>> x = np.arange(9)\n"
+    "    >>> y1, y2 = np.frexp(x)\n"
+    "    >>> y1\n"
+    "    array([ 0.   ,  0.5  ,  0.5  ,  0.75 ,  0.5  ,  0.625,  0.75 ,  0.875,\n"
+    "            0.5  ])\n"
+    "    >>> y2\n"
+    "    array([0, 1, 2, 2, 3, 3, 3, 3, 4])\n"
+    "    >>> y1 * 2**y2\n"
+    "    array([ 0.,  1.,  2.,  3.,  4.,  5.,  6.,  7.,  8.])\n"
+    "\n";
+
+
 static char ldexp_signatures[] = {
 #ifdef HAVE_LDEXPF
     NPY_HALF, NPY_INT, NPY_HALF,
@@ -266,6 +310,48 @@ static char ldexp_signatures[] = {
 #endif
 };
 
+static const char lddoc[] =
+    "    Returns x1 * 2**x2, element-wise.\n"
+    "\n"
+    "    The mantissas `x1` and twos exponents `x2` are used to construct\n"
+    "    floating point numbers ``x1 * 2**x2``.\n"
+    "\n"
+    "    Parameters\n"
+    "    ----------\n"
+    "    x1 : array_like\n"
+    "        Array of multipliers.\n"
+    "    x2 : array_like, int\n"
+    "        Array of twos exponents.\n"
+    "    out : ndarray, optional\n"
+    "        Output array for the result.\n"
+    "\n"
+    "    Returns\n"
+    "    -------\n"
+    "    y : ndarray or scalar\n"
+    "        The result of ``x1 * 2**x2``.\n"
+    "\n"
+    "    See Also\n"
+    "    --------\n"
+    "    frexp : Return (y1, y2) from ``x = y1 * 2**y2``, inverse to `ldexp`.\n"
+    "\n"
+    "    Notes\n"
+    "    -----\n"
+    "    Complex dtypes are not supported, they will raise a TypeError.\n"
+    "\n"
+    "    `ldexp` is useful as the inverse of `frexp`, if used by itself it is\n"
+    "    more clear to simply use the expression ``x1 * 2**x2``.\n"
+    "\n"
+    "    Examples\n"
+    "    --------\n"
+    "    >>> np.ldexp(5, np.arange(4))\n"
+    "    array([  5.,  10.,  20.,  40.], dtype=float32)\n"
+    "\n"
+    "    >>> x = np.arange(6)\n"
+    "    >>> np.ldexp(*np.frexp(x))\n"
+    "    array([ 0.,  1.,  2.,  3.,  4.,  5.])\n"
+    "\n";
+
+
 static void
 InitOtherOperators(PyObject *dictionary) {
     PyObject *f;
@@ -274,16 +360,14 @@ InitOtherOperators(PyObject *dictionary) {
     num = sizeof(frexp_functions) / sizeof(frexp_functions[0]);
     f = PyUFunc_FromFuncAndData(frexp_functions, blank3_data,
                                 frexp_signatures, num,
-                                1, 2, PyUFunc_None, "frexp",
-                                "Split the number, x, into a normalized"\
-                                " fraction (y1) and exponent (y2)",0);
+                                1, 2, PyUFunc_None, "frexp", frdoc, 0);
     PyDict_SetItemString(dictionary, "frexp", f);
     Py_DECREF(f);
 
     num = sizeof(ldexp_functions) / sizeof(ldexp_functions[0]);
-    f = PyUFunc_FromFuncAndData(ldexp_functions, blank6_data, ldexp_signatures, num,
-                                2, 1, PyUFunc_None, "ldexp",
-                                "Compute y = x1 * 2**x2.",0);
+    f = PyUFunc_FromFuncAndData(ldexp_functions, blank6_data,
+                                ldexp_signatures, num,
+                                2, 1, PyUFunc_None, "ldexp", lddoc, 0);
     PyDict_SetItemString(dictionary, "ldexp", f);
     Py_DECREF(f);