DOC: add entry to api_changes; improve some docstrings

efiring · efiring · commit dce381ebc260 · 2016-11-26T11:06:29.000-10:00
diff --git a/doc/api/api_changes.rst b/doc/api/api_changes.rst
@@ -22,7 +22,6 @@ Color of Axes
 The ``axisbg`` and ``axis_bgcolor`` properties on ``Axes`` have been
 deprecated in favor of ``facecolor``.
 
-
 GTK and GDK backends deprecated
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The GDK and GTK backends have been deprecated. These obsolete backends
@@ -41,6 +40,16 @@ CocoaAgg backend removed
 ~~~~~~~~~~~~~~~~~~~~~~~~
 The deprecated and not fully functional CocoaAgg backend has been removed.
 
+'hold' functionality deprecated
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'hold' keyword argument and all functions and methods related
+to it are deprecated, along with the 'axes.hold' `rcParams` entry.
+The behavior will remain consistent with the default ``hold=True``
+state that has long been in place.  Instead of using a function
+or keyword argument (``hold=False``) to change that behavior,
+explicitly clear the axes or figure as needed prior to subsequent
+plotting commands.
+
 
 `Artist.update` has return value
 --------------------------------
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -776,7 +776,11 @@ def figlegend(handles, labels, loc, **kwargs):
 
 ## Figure and Axes hybrid ##
 
-@deprecated("2.0")
+_hold_msg = """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):
     """
     Set the hold state.  If *b* is None (default), toggle the
@@ -786,12 +790,10 @@ def hold(b=None):
       hold(True)  # hold is on
       hold(False) # hold is off
 
-    When *hold* is *True*, subsequent plot commands will be added to
+    When *hold* is *True*, subsequent plot commands will add elements to
     the current axes.  When *hold* is *False*, the current axes and
     figure will be cleared on the next plot command.
 
-    Deprecated.  Future behavior will be consistent with the
-    long-time default of True.
     """
 
     fig = gcf()
@@ -812,17 +814,16 @@ def hold(b=None):
     # a second warning, but "Oh, well...".
     rc('axes', hold=b)
 
-@deprecated("2.0")
+@deprecated("2.0", message=_hold_msg)
 def ishold():
     """
     Return the hold status of the current axes.
 
-    Deprecated.
     """
     return gca()._hold
 
 
-@deprecated("2.0")
+@deprecated("2.0", message=_hold_msg)
 def over(func, *args, **kwargs):
     """
     Call a function with hold(True).
@@ -833,7 +834,6 @@ def over(func, *args, **kwargs):
 
     with ``hold(True)`` and then restores the hold state.
 
-    Deprecated.
     """
     ax = gca()
     h = ax._hold
