Ensure that documentation for dot, vdot, inner, alterdot, restoredot is the same, independent of whether these functions come from _dotblas or multiarray/numeric.py

2 files changed, 37 insertions, 119 deletions

diff --git a/numpy/core/blasdot/_dotblas.c b/numpy/core/blasdot/_dotblas.c
index 7f8007dd5..ae9af4a00 100644
--- a/numpy/core/blasdot/_dotblas.c
+++ b/numpy/core/blasdot/_dotblas.c
@@ -77,8 +77,9 @@ CDOUBLE_dot(void *a, npy_intp stridea, void *b, npy_intp strideb, void *res,
 
 static npy_bool altered=NPY_FALSE;
 
-static char doc_alterdot[] = "alterdot() changes all dot functions to use blas.";
-
+/*
+ * alterdot() changes all dot functions to use blas.
+ */
 static PyObject *
 dotblas_alterdot(PyObject *NPY_UNUSED(dummy), PyObject *args)
 {
@@ -112,8 +113,9 @@ dotblas_alterdot(PyObject *NPY_UNUSED(dummy), PyObject *args)
     return Py_None;
 }
 
-static char doc_restoredot[] = "restoredot() restores dots to defaults.";
-
+/*
+ * restoredot() restores dots to defaults.
+ */
 static PyObject *
 dotblas_restoredot(PyObject *NPY_UNUSED(dummy), PyObject *args)
 {
@@ -196,12 +198,13 @@ _bad_strides(PyArrayObject *ap)
     return 0;
 }
 
-static char doc_matrixproduct[] = \
-    "dot(a,b)\nReturns the dot product of a and b for arrays of " \
-    "floating point types.\nLike the generic numpy equivalent the " \
-    "product sum is over\nthe last dimension of a and the second-to-last "\
-    "dimension of b.\nNB: The first argument is not conjugated.";
-
+/*
+ * dot(a,b)
+ * Returns the dot product of a and b for arrays of floating point types.
+ * Like the generic numpy equivalent the product sum is over
+ * the last dimension of a and the second-to-last dimension of b.
+ * NB: The first argument is not conjugated.;
+ */
 static PyObject *
 dotblas_matrixproduct(PyObject *NPY_UNUSED(dummy), PyObject *args)
 {
@@ -796,11 +799,14 @@ dotblas_matrixproduct(PyObject *NPY_UNUSED(dummy), PyObject *args)
 }
 
 
-static char doc_innerproduct[] = \
-    "innerproduct(a,b)\nReturns the inner product of a and b for arrays of "\
-    "floating point types.\nLike the generic NumPy equivalent the product "\
-    "sum is over\nthe last dimension of a and b.\nNB: The first argument is "\
-    "not conjugated.";
+/*
+ * innerproduct(a,b)
+ *
+ * Returns the inner product of a and b for arrays of
+ * floating point types. Like the generic NumPy equivalent the product
+ * sum is over the last dimension of a and b.
+ * NB: The first argument is not conjugated.
+ */
 
 static PyObject *
 dotblas_innerproduct(PyObject *NPY_UNUSED(dummy), PyObject *args)
@@ -1048,9 +1054,12 @@ dotblas_innerproduct(PyObject *NPY_UNUSED(dummy), PyObject *args)
 }
 
 
-static char doc_vdot[] = "vdot(a,b)\nReturns the dot product of a and b for scalars and vectors\nof floating point and complex types.  The first argument, a, is conjugated.";
-
-
+/*
+ * vdot(a,b)
+ *
+ * Returns the dot product of a and b for scalars and vectors of
+ * floating point and complex types.  The first argument, a, is conjugated.
+ */
 static PyObject *dotblas_vdot(PyObject *NPY_UNUSED(dummy), PyObject *args) {
     PyObject *op1, *op2;
     PyArrayObject *ap1=NULL, *ap2=NULL, *ret=NULL;
@@ -1151,11 +1160,11 @@ static PyObject *dotblas_vdot(PyObject *NPY_UNUSED(dummy), PyObject *args) {
 }
 
 static struct PyMethodDef dotblas_module_methods[] = {
-    {"dot",  (PyCFunction)dotblas_matrixproduct, 1, doc_matrixproduct},
-    {"inner",   (PyCFunction)dotblas_innerproduct,  1, doc_innerproduct},
-    {"vdot", (PyCFunction)dotblas_vdot, 1, doc_vdot},
-    {"alterdot", (PyCFunction)dotblas_alterdot, 1, doc_alterdot},
-    {"restoredot", (PyCFunction)dotblas_restoredot, 1, doc_restoredot},
+    {"dot",  (PyCFunction)dotblas_matrixproduct, 1, NULL},
+    {"inner",   (PyCFunction)dotblas_innerproduct,  1, NULL},
+    {"vdot", (PyCFunction)dotblas_vdot, 1, NULL},
+    {"alterdot", (PyCFunction)dotblas_alterdot, 1, NULL},
+    {"restoredot", (PyCFunction)dotblas_restoredot, 1, NULL},
     {NULL, NULL, 0, NULL}		/* sentinel */
 };
 
diff --git a/numpy/core/numeric.py b/numpy/core/numeric.py
index ff2eb6ca9..57f36cfad 100644
--- a/numpy/core/numeric.py
+++ b/numpy/core/numeric.py
@@ -608,9 +608,6 @@ def convolve(a,v,mode='full'):
     mode = _mode_from_name(mode)
     return multiarray.correlate(a, v[::-1], mode)
 
-inner = multiarray.inner
-dot = multiarray.dot
-
 def outer(a,b):
     """
     Returns the outer product of two vectors.
@@ -654,110 +651,22 @@ def outer(a,b):
     b = asarray(b)
     return a.ravel()[:,newaxis]*b.ravel()[newaxis,:]
 
-def vdot(a, b):
-    """
-    Return the dot product of two vectors.
-
-    The vdot(`a`, `b`) function handles complex numbers differently than
-    dot(`a`, `b`).  If the first argument is complex the complex conjugate
-    of the first argument is used for the calculation of the dot product.
-
-    For 2-D arrays it is equivalent to matrix multiplication, and for 1-D
-    arrays to inner product of vectors (with complex conjugation of `a`).
-    For N dimensions it is a sum product over the last axis of `a` and
-    the second-to-last of `b`::
-
-        dot(a, b)[i,j,k,m] = sum(a[i,j,:] * b[k,:,m])
-
-    Parameters
-    ----------
-    a : array_like
-        If `a` is complex the complex conjugate is taken before calculation
-        of the dot product.
-    b : array_like
-        Second argument to the dot product.
-
-    Returns
-    -------
-    output : ndarray
-        Returns dot product of `a` and `b`.  Can be an int, float, or
-        complex depending on the types of `a` and `b`.
-
-    See Also
-    --------
-    dot : Return the dot product without using the complex conjugate of the
-          first argument.
-
-    Notes
-    -----
-    The dot product is the summation of element wise multiplication.
-
-    .. math::
-     a \\cdot b = \\sum_{i=1}^n a_i^*b_i = a_1^*b_1+a_2^*b_2+\\cdots+a_n^*b_n
-
-    Examples
-    --------
-    >>> a = np.array([1+2j,3+4j])
-    >>> b = np.array([5+6j,7+8j])
-    >>> np.vdot(a, b)
-    (70-8j)
-    >>> np.vdot(b, a)
-    (70+8j)
-    >>> a = np.array([[1, 4], [5, 6]])
-    >>> b = np.array([[4, 1], [2, 2]])
-    >>> np.vdot(a, b)
-    30
-    >>> np.vdot(b, a)
-    30
-
-    """
-    return dot(asarray(a).ravel().conj(), asarray(b).ravel())
-
 # try to import blas optimized dot if available
 try:
     # importing this changes the dot function for basic 4 types
     # to blas-optimized versions.
     from _dotblas import dot, vdot, inner, alterdot, restoredot
 except ImportError:
+    # docstrings are in add_newdocs.py
+    inner = multiarray.inner
+    dot = multiarray.dot
+    def vdot(a, b):
+        return dot(asarray(a).ravel().conj(), asarray(b).ravel())
     def alterdot():
-        """
-        Change `dot`, `vdot`, and `innerproduct` to use accelerated BLAS functions.
-
-        Typically, as a user of Numpy, you do not explicitly call this function. If
-        Numpy is built with an accelerated BLAS, this function is automatically
-        called when Numpy is imported.
-
-        When Numpy is built with an accelerated BLAS like ATLAS, these functions
-        are replaced to make use of the faster implementations.  The faster
-        implementations only affect float32, float64, complex64, and complex128
-        arrays. Furthermore, the BLAS API only includes matrix-matrix,
-        matrix-vector, and vector-vector products. Products of arrays with larger
-        dimensionalities use the built in functions and are not accelerated.
-
-        See Also
-        --------
-        restoredot : `restoredot` undoes the effects of `alterdot`.
-
-        """
         pass
     def restoredot():
-        """
-        Restore `dot`, `vdot`, and `innerproduct` to the default non-BLAS
-        implementations.
-
-        Typically, the user will only need to call this when troubleshooting and
-        installation problem, reproducing the conditions of a build without an
-        accelerated BLAS, or when being very careful about benchmarking linear
-        algebra operations.
-
-        See Also
-        --------
-        alterdot : `restoredot` undoes the effects of `alterdot`.
-
-        """
         pass
 
-
 def tensordot(a, b, axes=2):
     """
     Returns the tensor dot product for (ndim >= 1) arrays along an axes.