From 3e45bbfe574a599c9776c5d46aa3f75ed46e98b2 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Sun, 21 Jan 2018 23:48:14 +0100
Subject: [PATCH] update writing docs concerning explicit parameter lists

---
 doc/devel/documenting_mpl.rst | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
index a896777ca92f..caebde952ff8 100644
--- a/doc/devel/documenting_mpl.rst
+++ b/doc/devel/documenting_mpl.rst
@@ -337,7 +337,7 @@ An example docstring looks like:
 
         colors : array_like of colors, optional, default: 'k'
 
-        linestyles : ['solid' | 'dashed' | 'dashdot' | 'dotted'], optional
+        linestyles : {'solid', 'dashed', 'dashdot', 'dotted'}, optional
 
         label : string, optional, default: ''
 
@@ -389,10 +389,9 @@ to keep in mind:
          Parameters
          ----------
          projection :
-             ['aitoff' | 'hammer' | 'lambert' | 'mollweide' | \
-     'polar' | 'rectilinear'], optional
+             {'aitoff', 'hammer', 'lambert', 'mollweide', 'polar', \
+     'rectilinear'}, optional
              The projection type of the axes.
-        """
 
          ...
          """
@@ -411,6 +410,14 @@ to keep in mind:
      -------
      lines : `~matplotlib.collections.LineCollection`
 
+
+Deprecated formatting conventions
+---------------------------------
+* Formerly, we have used square brackets for explicit parameter lists
+  ``['solid' | 'dashed' | 'dotted']``. With numpydoc we have switched to their
+  standard using curly braces ``{'solid', 'dashed', 'dotted'}``.
+
+
 Linking to other code
 ---------------------
 To link to other methods, classes, or modules in Matplotlib you can encase