DOC: lib: Add more explanation of the weighted average calculation.

Also removed the incorrect comment from the docstring of `numpy.ma.average`
about the imaginary part of `weights` being ignored.

1 files changed, 5 insertions, 2 deletions

diff --git a/numpy/ma/extras.py b/numpy/ma/extras.py
index 639b3dd1f..de1aa3af8 100644
--- a/numpy/ma/extras.py
+++ b/numpy/ma/extras.py
@@ -549,8 +549,11 @@ def average(a, axis=None, weights=None, returned=False):
         The weights array can either be 1-D (in which case its length must be
         the size of `a` along the given axis) or of the same shape as `a`.
         If ``weights=None``, then all data in `a` are assumed to have a
-        weight equal to one.   If `weights` is complex, the imaginary parts
-        are ignored.
+        weight equal to one.  The 1-D calculation is::
+
+            avg = sum(a * weights) / sum(weights)
+
+        The only constraint on `weights` is that `sum(weights)` must not be 0.
     returned : bool, optional
         Flag indicating whether a tuple ``(result, sum of weights)``
         should be returned as output (True), or just the result (False).