DOC: Document xxxfit functions in the polynomial package modules.

1 files changed, 28 insertions, 20 deletions

diff --git a/numpy/polynomial/laguerre.py b/numpy/polynomial/laguerre.py
index 15ea8d870..489ecb8a2 100644
--- a/numpy/polynomial/laguerre.py
+++ b/numpy/polynomial/laguerre.py
@@ -1296,9 +1296,16 @@ def lagfit(x, y, deg, rcond=None, full=False, w=None):
     """
     Least squares fit of Laguerre series to data.
 
-    Fit a Laguerre series ``p(x) = p[0] * P_{0}(x) + ... + p[deg] *
-    P_{deg}(x)`` of degree `deg` to points `(x, y)`. Returns a vector of
-    coefficients `p` that minimises the squared error.
+    Return the coefficients of a Laguerre series of degree `deg` that is the
+    least squares fit to the data values `y` given at points `x`. If `y` is
+    1-D the returned coefficients will also be 1-D. If `y` is 2-D multiple
+    fits are done, one for each column of `y`, and the resulting
+    coefficients are stored in the corresponding columns of a 2-D return.
+    The fitted polynomial(s) are in the form
+
+    .. math::  p(x) = c_0 + c_1 * L_1(x) + ... + c_n * L_n(x),
+
+    where `n` is `deg`.
 
     Parameters
     ----------
@@ -1349,41 +1356,42 @@ def lagfit(x, y, deg, rcond=None, full=False, w=None):
 
     See Also
     --------
+    chebfit, legfit, polyfit, hermfit, hermefit
     lagval : Evaluates a Laguerre series.
-    lagvander : Vandermonde matrix of Laguerre series.
-    polyfit : least squares fit using polynomials.
-    chebfit : least squares fit using Chebyshev series.
+    lagvander : pseudo Vandermonde matrix of Laguerre series.
+    lagweight : Laguerre weight function.
     linalg.lstsq : Computes a least-squares fit from the matrix.
     scipy.interpolate.UnivariateSpline : Computes spline fits.
 
     Notes
     -----
-    The solution are the coefficients ``c[i]`` of the Laguerre series
-    ``P(x)`` that minimizes the squared error
+    The solution is the coefficients of the Laguerre series `p` that
+    minimizes the sum of the weighted squared errors
 
-    ``E = \\sum_j |y_j - P(x_j)|^2``.
+    .. math:: E = \\sum_j w_j^2 * |y_j - p(x_j)|^2,
 
-    This problem is solved by setting up as the overdetermined matrix
-    equation
+    where the :math:`w_j` are the weights. This problem is solved by
+    setting up as the (typically) overdetermined matrix equation
 
-    ``V(x)*c = y``,
+    .. math:: V(x) * c = w * y,
 
-    where ``V`` is the Vandermonde matrix of `x`, the elements of ``c`` are
-    the coefficients to be solved for, and the elements of `y` are the
+    where `V` is the weighted pseudo Vandermonde matrix of `x`, `c` are the
+    coefficients to be solved for, `w` are the weights, and `y` are the
     observed values.  This equation is then solved using the singular value
-    decomposition of ``V``.
+    decomposition of `V`.
 
-    If some of the singular values of ``V`` are so small that they are
+    If some of the singular values of `V` are so small that they are
     neglected, then a `RankWarning` will be issued. This means that the
     coeficient values may be poorly determined. Using a lower order fit
     will usually get rid of the warning.  The `rcond` parameter can also be
     set to a value smaller than its default, but the resulting fit may be
     spurious and have large contributions from roundoff error.
 
-    Fits using Laguerre series are usually better conditioned than fits
-    using power series, but much can depend on the distribution of the
-    sample points and the smoothness of the data. If the quality of the fit
-    is inadequate splines may be a good alternative.
+    Fits using Laguerre series are probably most useful when the data can
+    be approximated by ``sqrt(w(x)) * p(x)``, where `w(x)` is the Laguerre
+    weight. In that case the wieght ``sqrt(w(x[i])`` should be used
+    together with data values ``y[i]/sqrt(w(x[i])``. The weight function is
+    available as `lagweight`.
 
     References
     ----------