Improve deprecation documentation. Closes #7643

doc/api/api_changes.rst

@@ -192,6 +192,15 @@ figure which is raising an error on draw.  The previous behavior would only mark
 a figure as not stale after a full re-draw succeeded.
 
 
+The spectral colormap is now nipy_spectral
+------------------------------------------
+
+The colormaps formerly known as ``spectral`` and ``spectral_r`` have been
+replaced by ``nipy_spectral`` and ``nipy_spectral_r`` since matplotlib
+1.3.0. Even though the colormap was deprecated in matplotlib 1.3.0, it never
+raised a warning. As of matplotlib 2.0.0, using the old names raises a
+deprecation warning. In the future, using the old names will raise an error.
+
 Changes in 1.5.3
 ================
 

lib/matplotlib/axes/_base.py

@@ -42,6 +42,10 @@
 is_string_like = cbook.is_string_like
 is_sequence_of_strings = cbook.is_sequence_of_strings
 
+_hold_msg = """axes.hold is deprecated.
+    See the API Changes document (http://matplotlib.org/api/api_changes.html)
+    for more details."""
+
 
 def _process_plot_format(fmt):
     """
@@ -1202,7 +1206,7 @@ def ishold(self):
 
         return self._hold
 
-    @cbook.deprecated("2.0")
+    @cbook.deprecated("2.0", message=_hold_msg)
     def hold(self, b=None):
         """
         Set the hold state

lib/matplotlib/pyplot.py

@@ -775,9 +775,10 @@ def figlegend(handles, labels, loc, **kwargs):
 
 ## Figure and Axes hybrid ##
 
-_hold_msg = """Future behavior will be consistent with the long-time
-    default: plot commands add elements without first
-    clearing the Axes and/or Figure."""
+_hold_msg = """pyplot.hold is deprecated.
+    Future behavior will be consistent with the long-time default:
+    plot commands add elements without first clearing the
+    Axes and/or Figure."""
 
 @deprecated("2.0", message=_hold_msg)
 def hold(b=None):