Add/edit documentation for mean, std, var.

3 files changed, 305 insertions, 30 deletions

diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py
index 7a3ec13fa..34da3d758 100644
--- a/numpy/add_newdocs.py
+++ b/numpy/add_newdocs.py
@@ -332,7 +332,7 @@ add_newdoc('numpy.core.multiarray','set_string_function',
 add_newdoc('numpy.core.multiarray','set_numeric_ops',
     """set_numeric_ops(op=func, ...)
 
-    Set some or all of the number methods for all array objects.  Don't
+    Set some or all of the number methods for all array objects.  Do not
     forget **dict can be used as the argument list.  Return the functions
     that were replaced, which can be stored and set later.
 
@@ -810,7 +810,7 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('getfield',
     """a.getfield(dtype, offset) -> field of array as given type.
 
     Returns a field of the given array as a certain type. A field is a view of
-    the array's data with each itemsize determined by the given type and the
+    the array data with each itemsize determined by the given type and the
     offset into the current array.
 
     """))
@@ -832,15 +832,37 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('max',
 
 
 add_newdoc('numpy.core.multiarray', 'ndarray', ('mean',
-    """a.mean(axis=None, dtype=None)
+    """a.mean(axis=None, dtype=None, out=None) -> mean
 
-      Average the array over the given axis.  If the axis is None,
-      average over all dimensions of the array.  Equivalent to
+    Returns the average of the array elements.  The average is taken over the
+    flattened array by default, otherwise over the specified axis.
+    
+    :Parameters:
+        axis : integer
+            Axis along which the means are computed. The default is
+            to compute the standard deviation of the flattened array.
+        dtype : type
+            Type to use in computing the means. For arrays of
+            integer type the default is float32, for arrays of float types it
+            is the same as the array type.
+        out : ndarray
+            Alternative output array in which to place the result. It must have
+            the same shape as the expected output but the type will be cast if
+            necessary.
 
-        a.sum(axis, dtype) / size(a, axis).
+    :Returns:
+        mean : The return type varies, see above.
+            A new array holding the result is returned unless out is specified,
+            in which case a reference to out is returned.
 
-      The optional dtype argument is the data type for intermediate
-      calculations in the sum.
+    :SeeAlso:
+        - var : variance
+        - std : standard deviation
+
+    Notes
+    -----
+        The mean is the sum of the elements along the axis divided by the
+        number of elements.
 
     """))
 
@@ -1072,15 +1094,39 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('squeeze',
 add_newdoc('numpy.core.multiarray', 'ndarray', ('std',
     """a.std(axis=None, dtype=None, out=None) -> standard deviation.
 
-    The standard deviation isa measure of the spread of a
-    distribution.
+    Returns the standard deviation of the array elements, a measure of the
+    spread of a distribution. The standard deviation is computed for the
+    flattened array by default, otherwise over the specified axis.
+
+    :Parameters:
+        axis : integer
+            Axis along which the standard deviation is computed. The default is
+            to compute the standard deviation of the flattened array.
+        dtype : type
+            Type to use in computing the standard deviation. For arrays of
+            integer type the default is float32, for arrays of float types it
+            is the same as the array type.
+        out : ndarray
+            Alternative output array in which to place the result. It must have
+            the same shape as the expected output but the type will be cast if
+            necessary.
+
+    :Returns:
+        standard deviation : The return type varies, see above.
+            A new array holding the result is returned unless out is specified,
+            in which case a reference to out is returned.
+
+    :SeeAlso:
+        - var : variance
+        - mean : average
 
-    The standard deviation is the square root of the average of the
-    squared deviations from the mean, i.e.
-        std = sqrt(mean((x - x.mean())**2,axis=0)).
+    Notes
+    -----
 
-    For multidimensional arrays, std is computed by default along the
-    first axis.
+      The standard deviation is the square root of the average of the squared
+      deviations from the mean, i.e. var = sqrt(mean((x - x.mean())**2)).  The
+      computed standard deviation is biased, i.e., the mean is computed by
+      dividing by the number of elements, N, rather than by N-1.
 
     """))
 
@@ -1224,7 +1270,41 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('transpose',
 
 
 add_newdoc('numpy.core.multiarray', 'ndarray', ('var',
-    """a.var(axis=None, dtype=None)
+    """a.var(axis=None, dtype=None, out=None) -> variance
+
+    Returns the variance of the array elements, a measure of the spread of a
+    distribution.  The variance is computed for the flattened array by default,
+    otherwise over the specified axis.
+
+    :Parameters:
+        axis : integer
+            Axis along which the variance is computed. The default is to
+            compute the variance of the flattened array.
+        dtype : type
+            Type to use in computing the variance. For arrays of integer type
+            the default is float32, for arrays of float types it is the same as
+            the array type.
+        out : ndarray
+            Alternative output array in which to place the result. It must have
+            the same shape as the expected output but the type will be cast if
+            necessary.
+
+    :Returns:
+        variance : The return type varies, see above.
+            A new array holding the result is returned unless out is specified,
+            in which case a reference to out is returned.
+
+    :SeeAlso:
+        - std : standard deviation
+        - mean: average
+
+    Notes
+    -----
+
+      The variance is the average of the squared deviations from the mean, i.e.
+      var = mean((x - x.mean())**2).  The computed variance is biased, i.e.,
+      the mean is computed by dividing by the number of elements, N, rather
+      than by N-1.
 
     """))
 
diff --git a/numpy/core/defmatrix.py b/numpy/core/defmatrix.py
index 33efe2b99..1550d2444 100644
--- a/numpy/core/defmatrix.py
+++ b/numpy/core/defmatrix.py
@@ -241,12 +241,121 @@ class matrix(N.ndarray):
         return N.ndarray.sum(self, axis, dtype, out)._align(axis)
 
     def mean(self, axis=None, out=None):
+        """Compute the mean along the specified axis.
+
+        Returns the average of the array elements.  The average is taken over
+        the flattened array by default, otherwise over the specified axis.
+
+        :Parameters:
+            axis : integer
+                Axis along which the means are computed. The default is
+                to compute the standard deviation of the flattened array.
+            dtype : type
+                Type to use in computing the means. For arrays of integer type
+                the default is float32, for arrays of float types it is the
+                same as the array type.
+            out : ndarray
+                Alternative output array in which to place the result. It must
+                have the same shape as the expected output but the type will be
+                cast if necessary.
+
+        :Returns:
+            mean : The return type varies, see above.
+                A new array holding the result is returned unless out is
+                specified, in which case a reference to out is returned.
+
+        :SeeAlso:
+            - var : variance
+            - std : standard deviation
+
+        Notes
+        -----
+            The mean is the sum of the elements along the axis divided by the
+            number of elements.
+
+        """
         return N.ndarray.mean(self, axis, out)._align(axis)
 
     def std(self, axis=None, dtype=None, out=None):
+        """Compute the standard deviation along the specified axis.
+
+        Returns the standard deviation of the array elements, a measure of the
+        spread of a distribution. The standard deviation is computed for the
+        flattened array by default, otherwise over the specified axis.
+
+        :Parameters:
+            axis : integer
+                Axis along which the standard deviation is computed. The
+                default is to compute the standard deviation of the flattened
+                array.
+            dtype : type
+                Type to use in computing the standard deviation. For arrays of
+                integer type the default is float32, for arrays of float types
+                it is the same as the array type.
+            out : ndarray
+                Alternative output array in which to place the result. It must
+                have the same shape as the expected output but the type will be
+                cast if necessary.
+
+        :Returns:
+            standard deviation : The return type varies, see above.
+                A new array holding the result is returned unless out is
+                specified, in which case a reference to out is returned.
+
+        :SeeAlso:
+            - var : variance
+            - mean : average
+
+        Notes
+        -----
+
+          The standard deviation is the square root of the average of the
+          squared deviations from the mean, i.e. var = sqrt(mean((x -
+          x.mean())**2)).  The computed standard deviation is biased, i.e., the
+          mean is computed by dividing by the number of elements, N, rather
+          than by N-1.
+
+        """
         return N.ndarray.std(self, axis, dtype, out)._align(axis)
 
     def var(self, axis=None, dtype=None, out=None):
+        """Compute the variance along the specified axis.
+
+        Returns the variance of the array elements, a measure of the spread of
+        a distribution.  The variance is computed for the flattened array by
+        default, otherwise over the specified axis.
+
+        :Parameters:
+            axis : integer
+                Axis along which the variance is computed. The default is to
+                compute the variance of the flattened array.
+            dtype : type
+                Type to use in computing the variance. For arrays of integer
+                type the default is float32, for arrays of float types it is
+                the same as the array type.
+            out : ndarray
+                Alternative output array in which to place the result. It must
+                have the same shape as the expected output but the type will be
+                cast if necessary.
+
+        :Returns:
+            variance : depends, see above
+                A new array holding the result is returned unless out is
+                specified, in which case a reference to out is returned.
+
+        :SeeAlso:
+            - std : standard deviation
+            - mean : average
+
+        Notes
+        -----
+
+          The variance is the average of the squared deviations from the mean,
+          i.e.  var = mean((x - x.mean())**2).  The computed variance is
+          biased, i.e., the mean is computed by dividing by the number of
+          elements, N, rather than by N-1.
+
+        """
         return N.ndarray.var(self, axis, dtype, out)._align(axis)
 
     def prod(self, axis=None, dtype=None, out=None):
diff --git a/numpy/core/fromnumeric.py b/numpy/core/fromnumeric.py
index 573868b61..c96505521 100644
--- a/numpy/core/fromnumeric.py
+++ b/numpy/core/fromnumeric.py
@@ -691,12 +691,38 @@ def round_(a, decimals=0, out=None):
 around = round_
 
 def mean(a, axis=None, dtype=None, out=None):
-    """mean(a, axis=None, dtype=None)
-    Return the arithmetic mean.
+    """Compute the mean along the specified axis.
 
-    The mean is the sum of the elements divided by the number of elements.
+    Returns the average of the array elements.  The average is taken over the
+    flattened array by default, otherwise over the specified axis.
+
+    :Parameters:
+        axis : integer
+            Axis along which the means are computed. The default is
+            to compute the standard deviation of the flattened array.
+        dtype : type
+            Type to use in computing the means. For arrays of
+            integer type the default is float32, for arrays of float types it
+            is the same as the array type.
+        out : ndarray
+            Alternative output array in which to place the result. It must have
+            the same shape as the expected output but the type will be cast if
+            necessary.
+
+    :Returns:
+        mean : The return type varies, see above.
+            A new array holding the result is returned unless out is specified,
+            in which case a reference to out is returned.
+
+    :SeeAlso:
+        - var : variance
+        - std : standard deviation
+
+    Notes
+    -----
+        The mean is the sum of the elements along the axis divided by the
+        number of elements.
 
-    See also: average
     """
     try:
         mean = a.mean
@@ -704,14 +730,44 @@ def mean(a, axis=None, dtype=None, out=None):
         return _wrapit(a, 'mean', axis, dtype, out)
     return mean(axis, dtype, out)
 
+
 def std(a, axis=None, dtype=None, out=None):
-    """std(sample, axis=None, dtype=None)
-    Return the standard deviation, a measure of the spread of a distribution.
+    """Compute the standard deviation along the specified axis.
+
+    Returns the standard deviation of the array elements, a measure of the
+    spread of a distribution. The standard deviation is computed for the
+    flattened array by default, otherwise over the specified axis.
+
+    :Parameters:
+        axis : integer
+            Axis along which the standard deviation is computed. The default is
+            to compute the standard deviation of the flattened array.
+        dtype : type
+            Type to use in computing the standard deviation. For arrays of
+            integer type the default is float32, for arrays of float types it
+            is the same as the array type.
+        out : ndarray
+            Alternative output array in which to place the result. It must have
+            the same shape as the expected output but the type will be cast if
+            necessary.
+
+    :Returns:
+        standard deviation : The return type varies, see above.
+            A new array holding the result is returned unless out is specified,
+            in which case a reference to out is returned.
+
+    :SeeAlso:
+        - var : variance
+        - mean : average
+
+    Notes
+    -----
 
-    The standard deviation is the square root of the average of the squared
-    deviations from the mean, i.e. std = sqrt(mean((x - x.mean())**2)).
+      The standard deviation is the square root of the average of the squared
+      deviations from the mean, i.e. var = sqrt(mean((x - x.mean())**2)).  The
+      computed standard deviation is biased, i.e., the mean is computed by
+      dividing by the number of elements, N, rather than by N-1.
 
-    See also: var
     """
     try:
         std = a.std
@@ -719,14 +775,44 @@ def std(a, axis=None, dtype=None, out=None):
         return _wrapit(a, 'std', axis, dtype, out)
     return std(axis, dtype, out)
 
+
 def var(a, axis=None, dtype=None, out=None):
-    """var(sample, axis=None, dtype=None)
-    Return the variance, a measure of the spread of a distribution.
+    """Compute the variance along the specified axis.
+
+    Returns the variance of the array elements, a measure of the spread of a
+    distribution.  The variance is computed for the flattened array by default,
+    otherwise over the specified axis.
+
+    :Parameters:
+        axis : integer
+            Axis along which the variance is computed. The default is to
+            compute the variance of the flattened array.
+        dtype : type
+            Type to use in computing the variance. For arrays of integer type
+            the default is float32, for arrays of float types it is the same as
+            the array type.
+        out : ndarray
+            Alternative output array in which to place the result. It must have
+            the same shape as the expected output but the type will be cast if
+            necessary.
+
+    :Returns:
+        variance : depends, see above
+            A new array holding the result is returned unless out is specified,
+            in which case a reference to out is returned.
+
+    :SeeAlso:
+        - std : standard deviation
+        - mean : average
+
+    Notes
+    -----
 
-    The variance is the average of the squared deviations from the mean,
-    i.e. var = mean((x - x.mean())**2).
+      The variance is the average of the squared deviations from the mean, i.e.
+      var = mean((x - x.mean())**2).  The computed variance is biased, i.e.,
+      the mean is computed by dividing by the number of elements, N, rather
+      than by N-1.
 
-    See also: std
     """
     try:
         var = a.var