ENH: Add the polynomial module to the documentation.

Also:
1. Note that the polynomial package is preferred over poly1d.

2. Remove deprecation of mapparms in __init__.py as it interferes with the
   documention of the method of the same name. This is probably safe as it
   is unlikely to be used yet.

3. Make some improvements to the documentation in polytemplate.

6 files changed, 69 insertions, 18 deletions

diff --git a/doc/source/reference/routines.poly.rst b/doc/source/reference/routines.polynomials.poly1d.rst
index f30b2c884..7eef53ce2 100644
--- a/doc/source/reference/routines.poly.rst
+++ b/doc/source/reference/routines.polynomials.poly1d.rst
@@ -1,5 +1,5 @@
-Polynomials
-***********
+Poly1d
+======
 
 .. currentmodule:: numpy
 
diff --git a/doc/source/reference/routines.polynomials.polynomial.rst b/doc/source/reference/routines.polynomials.polynomial.rst
new file mode 100644
index 000000000..aa92ce8fc
--- /dev/null
+++ b/doc/source/reference/routines.polynomials.polynomial.rst
@@ -0,0 +1,16 @@
+Polynomial Package (:mod:`numpy.polynomial`)
+============================================
+
+.. currentmodule:: numpy.polynomial
+
+Polynomial Classes
+------------------
+.. autosummary::
+   :toctree: generated/
+
+   Polynomial
+   Chebyshev
+   Legendre
+   Hermite
+   HermiteE
+   Laguerre
diff --git a/doc/source/reference/routines.polynomials.rst b/doc/source/reference/routines.polynomials.rst
new file mode 100644
index 000000000..59d6bc499
--- /dev/null
+++ b/doc/source/reference/routines.polynomials.rst
@@ -0,0 +1,14 @@
+Polynomials
+***********
+
+The poly1d functions are considered outdated but are retained for
+backward compatibility. New software needing polynomials should
+use the classes in the Polynomial Package.
+
+.. toctree::
+   :maxdepth: 2
+
+   routines.polynomials.polynomial
+   routines.polynomials.poly1d
+
+
diff --git a/doc/source/reference/routines.rst b/doc/source/reference/routines.rst
index c97a3d244..fb53aac3b 100644
--- a/doc/source/reference/routines.rst
+++ b/doc/source/reference/routines.rst
@@ -29,7 +29,7 @@ indentation.
    routines.statistics
    routines.math
    routines.functional
-   routines.poly
+   routines.polynomials
    routines.datetime
    routines.financial
    routines.set
diff --git a/numpy/polynomial/__init__.py b/numpy/polynomial/__init__.py
index 851bde109..48c679ce1 100644
--- a/numpy/polynomial/__init__.py
+++ b/numpy/polynomial/__init__.py
@@ -298,10 +298,13 @@ def getdomain(x) :
     from numpy.polynomial.polyutils import getdomain
     return getdomain(x)
 
-@deprecate(message='Please import mapparms from numpy.polynomial.polyutils')
-def mapparms(old, new) :
-    from numpy.polynomial.polyutils import mapparms
-    return mapparms(old, new)
+# Just remove this function as it screws up the documentation of the same
+# named class method.
+#
+#@deprecate(message='Please import mapparms from numpy.polynomial.polyutils')
+#def mapparms(old, new) :
+#    from numpy.polynomial.polyutils import mapparms
+#    return mapparms(old, new)
 
 @deprecate(message='Please import mapdomain from numpy.polynomial.polyutils')
 def mapdomain(x, old, new) :
diff --git a/numpy/polynomial/polytemplate.py b/numpy/polynomial/polytemplate.py
index 657b48508..3763123dc 100644
--- a/numpy/polynomial/polytemplate.py
+++ b/numpy/polynomial/polytemplate.py
@@ -25,6 +25,10 @@ import numpy as np
 class $name(pu.PolyBase) :
     """A $name series class.
 
+    $name instances provide the standard Python numerical methods '+',
+    '-', '*', '//', '%', 'divmod', '**', and '()' as well as the listed
+    methods.
+
     Parameters
     ----------
     coef : array_like
@@ -60,10 +64,10 @@ class $name(pu.PolyBase) :
 
     Notes
     -----
-    It is important to specify the domain for many uses of graded polynomial,
-    for instance in fitting data. This is because many of the important
-    properties of the polynomial basis only hold in a specified interval and
-    thus the data must be mapped into that domain in order to benefit.
+    It is important to specify the domain in many cases, for instance in
+    fitting data, because many of the important properties of the
+    polynomial basis only hold in a specified interval and consequently
+    the data must be mapped into that interval in order to benefit.
 
     Examples
     --------
@@ -408,13 +412,12 @@ class $name(pu.PolyBase) :
     def copy(self) :
         """Return a copy.
 
-        A new instance of $name is returned that has the same
-        coefficients and domain as the current instance.
+        Return a copy of the current $name instance.
 
         Returns
         -------
         new_instance : $name
-            New instance of $name with the same coefficients and domain.
+            Copy of current instance.
 
         """
         return self.__class__(self.coef, self.domain, self.window)
@@ -514,12 +517,15 @@ class $name(pu.PolyBase) :
         Parameters
         ----------
         domain : array_like, optional
-            The domain of the new series type instance. If the value is None,
-            then the default domain of `kind` is used.
+            The domain of the converted series. If the value is None,
+            the default domain of `kind` is used.
         kind : class, optional
             The polynomial series type class to which the current instance
             should be converted. If kind is None, then the class of the
             current instance is used.
+        window : array_like, optional
+            The window of the converted series. If the value is None,
+            the default window of `kind` is used.
 
         Returns
         -------
@@ -767,9 +773,21 @@ class $name(pu.PolyBase) :
 
     @staticmethod
     def fromroots(roots, domain=$domain, window=$domain) :
-        """Return $name object with specified roots.
+        """Return $name instance with specified roots.
+
+        Returns an instance of $name representing the product
+        ``(x - r[0])*(x - r[1])*...*(x - r[n-1])``, where ``r`` is the
+        list of roots.
 
-        See ${nick}fromroots for full documentation.
+        Parameters
+        ----------
+        roots : array_like
+            List of roots.
+
+        Returns
+        -------
+        object : $name
+            Series with the specified roots.
 
         See Also
         --------