diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
index b37715d283ad..7cd999ac4cf8 100644
--- a/lib/matplotlib/pyplot.py
+++ b/lib/matplotlib/pyplot.py
@@ -1,19 +1,21 @@
 # Note: The first part of this file can be modified in place, but the latter
 # part is autogenerated by the boilerplate.py script.
+
 """
-Provides a MATLAB-like plotting framework.
+`matplotlib.pyplot` is a state-based interface to matplotlib. It provides
+a MATLAB-like way of plotting.
 
-:mod:`~matplotlib.pylab` combines pyplot with numpy into a single namespace.
-This is convenient for interactive work, but for programming it
-is recommended that the namespaces be kept separate, e.g.::
+pyplot is mainly intended for interactive plots and simple cases of programmatic
+plot generation::
 
     import numpy as np
     import matplotlib.pyplot as plt
 
-    x = np.arange(0, 5, 0.1);
+    x = np.arange(0, 5, 0.1)
     y = np.sin(x)
     plt.plot(x, y)
 
+The object-oriented API is recommended for more complex plots.
 """
 from __future__ import (absolute_import, division, print_function,
                         unicode_literals)
@@ -260,13 +262,13 @@ def isinteractive():
 
 
 def ioff():
-    'Turn interactive mode off.'
+    """Turn interactive mode off."""
     matplotlib.interactive(False)
     uninstall_repl_displayhook()
 
 
 def ion():
-    'Turn interactive mode on.'
+    """Turn interactive mode on."""
     matplotlib.interactive(True)
     install_repl_displayhook()
 
@@ -281,6 +283,8 @@ def pause(interval):
     This can be used for crude animation.  For more complex animation, see
     :mod:`matplotlib.animation`.
 
+    Note
+    ----
     This function is experimental; its behavior may be changed or extended in a
     future release.
     """
@@ -580,8 +584,7 @@ def _auto_draw_if_interactive(fig, val):
 
 
 def gcf():
-    "Get a reference to the current figure."
-
+    """Get a reference to the current figure."""
     figManager = _pylab_helpers.Gcf.get_active()
     if figManager is not None:
         return figManager.canvas.figure
@@ -599,7 +602,7 @@ def get_fignums():
 
 
 def get_figlabels():
-    "Return a list of existing figure labels."
+    """Return a list of existing figure labels."""
     figManagers = _pylab_helpers.Gcf.get_all_fig_managers()
     figManagers.sort(key=lambda m: m.num)
     return [m.canvas.figure.get_label() for m in figManagers]
@@ -629,9 +632,9 @@ def close(*args):
 
     ``close()`` by itself closes the current figure
 
-    ``close(h)`` where *h* is a :class:`Figure` instance, closes that figure
+    ``close(fig)`` closes the `~.Figure` instance *fig*
 
-    ``close(num)`` closes figure number *num*
+    ``close(num)`` closes the figure number *num*
 
     ``close(name)`` where *name* is a string, closes figure with that label
 
@@ -827,7 +830,6 @@ def hold(b=None):
 def ishold():
     """
     Return the hold status of the current axes.
-
     """
     return gca()._hold
 
@@ -1325,8 +1327,8 @@ def tight_layout(pad=1.08, h_pad=None, w_pad=None, rect=None):
     """
     Automatically adjust subplot parameters to give specified padding.
 
-    Parameters:
-
+    Parameters
+    ----------
     pad : float
         padding between the figure edge and the edges of subplots, as a fraction of the font-size.
     h_pad, w_pad : float
@@ -1336,8 +1338,8 @@ def tight_layout(pad=1.08, h_pad=None, w_pad=None, rect=None):
         (left, bottom, right, top) in the normalized figure
         coordinate that the whole subplots area (including
         labels) will fit into. Default is (0, 0, 1, 1).
-    """
 
+    """
     fig = gcf()
     fig.tight_layout(pad=pad, h_pad=h_pad, w_pad=w_pad, rect=rect)