From 7578c745aebc776d79a89758f1167c0718295983 Mon Sep 17 00:00:00 2001
From: Antony Lee <anntzer.lee@gmail.com>
Date: Thu, 28 Feb 2019 18:41:15 +0100
Subject: [PATCH] Deprecate TextWithDash.

TextWithDash appears to be an ancestral version of Annotation that was
added over two commits in 2005 (6a4d343, fe80816), revised once in 2006
and another time in 2008, and never touched since then.

While it "works", its implementation is 400 lines long, it is only
mentioned by a single example (dashpointlabel.py), somewhat complicates
Axes.text(), and is likely rarely used and replaceable by Annotation for
most use cases.

Hence, deprecate it, keeping open the option to undeprecate if this
turns out to be too disruptive.
---
 doc/api/next_api_changes/2019-03-01-AL.rst             | 5 +++++
 examples/text_labels_and_annotations/dashpointlabel.py | 6 ++++++
 lib/matplotlib/axes/_axes.py                           | 4 +++-
 lib/matplotlib/figure.py                               | 1 +
 lib/matplotlib/pyplot.py                               | 4 +++-
 lib/matplotlib/text.py                                 | 1 +
 6 files changed, 19 insertions(+), 2 deletions(-)
 create mode 100644 doc/api/next_api_changes/2019-03-01-AL.rst

diff --git a/doc/api/next_api_changes/2019-03-01-AL.rst b/doc/api/next_api_changes/2019-03-01-AL.rst
new file mode 100644
index 000000000000..82dea08422d1
--- /dev/null
+++ b/doc/api/next_api_changes/2019-03-01-AL.rst
@@ -0,0 +1,5 @@
+Deprecations
+````````````
+
+The ``text.TextWithDash`` class and the ``withdash`` keyword argument to
+``text()`` is deprecated.  Consider using ``annotate()`` instead.
diff --git a/examples/text_labels_and_annotations/dashpointlabel.py b/examples/text_labels_and_annotations/dashpointlabel.py
index b795c70e6414..96a8b7564613 100644
--- a/examples/text_labels_and_annotations/dashpointlabel.py
+++ b/examples/text_labels_and_annotations/dashpointlabel.py
@@ -4,8 +4,13 @@
 ===============
 
 """
+
+import warnings
+
 import matplotlib.pyplot as plt
 
+warnings.simplefilter("ignore")  # Ignore deprecation of withdash.
+
 DATA = ((1, 3),
         (2, 4),
         (3, 1),
@@ -36,5 +41,6 @@
 
 ax.set_xlim((0, 5))
 ax.set_ylim((0, 5))
+ax.set(title="NOTE: The withdash parameter is deprecated.")
 
 plt.show()
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
index 6ecfa9eb4eef..41dce21006fb 100644
--- a/lib/matplotlib/axes/_axes.py
+++ b/lib/matplotlib/axes/_axes.py
@@ -673,6 +673,7 @@ def secondary_yaxis(self, location, *, functions=None, **kwargs):
             raise ValueError('secondary_yaxis location must be either '
                              'a float or "left"/"right"')
 
+    @cbook._delete_parameter("3.1", "withdash")
     def text(self, x, y, s, fontdict=None, withdash=False, **kwargs):
         """
         Add text to the axes.
@@ -748,7 +749,8 @@ def text(self, x, y, s, fontdict=None, withdash=False, **kwargs):
         # the withdash kwarg and simply delegate whether there's
         # a dash to TextWithDash and dashlength.
 
-        if withdash:
+        if (withdash
+                and withdash is not cbook.deprecation._deprecated_parameter):
             t = mtext.TextWithDash(x, y, text=s)
         else:
             t = mtext.Text(x, y, text=s)
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
index 6919dbf1c4f5..653455b0b6dd 100644
--- a/lib/matplotlib/figure.py
+++ b/lib/matplotlib/figure.py
@@ -1804,6 +1804,7 @@ def legend(self, *args, **kwargs):
         self.stale = True
         return l
 
+    @cbook._delete_parameter("3.1", "withdash")
     @docstring.dedent_interpd
     def text(self, x, y, s, fontdict=None, withdash=False, **kwargs):
         """
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
index ecf84248c1da..9f7b640e62ca 100644
--- a/lib/matplotlib/pyplot.py
+++ b/lib/matplotlib/pyplot.py
@@ -2936,7 +2936,9 @@ def table(
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
 @docstring.copy(Axes.text)
-def text(x, y, s, fontdict=None, withdash=False, **kwargs):
+def text(
+        x, y, s, fontdict=None,
+        withdash=cbook.deprecation._deprecated_parameter, **kwargs):
     return gca().text(x, y, s, fontdict=fontdict, withdash=withdash, **kwargs)
 
 
diff --git a/lib/matplotlib/text.py b/lib/matplotlib/text.py
index 3ceffaf3777a..81222d0b42d9 100644
--- a/lib/matplotlib/text.py
+++ b/lib/matplotlib/text.py
@@ -1245,6 +1245,7 @@ def set_fontname(self, fontname):
 docstring.dedent_interpd(Text.__init__)
 
 
+@cbook.deprecated("3.1", alternative="Annotation")
 class TextWithDash(Text):
     """
     This is basically a :class:`~matplotlib.text.Text` with a dash