DOC: clarified comments in code about what this code is doing

tacaswell · tacaswell · commit 676f3eb2b02d · 2020-01-28T15:39:19.000-05:00
diff --git a/lib/matplotlib/cbook/__init__.py b/lib/matplotlib/cbook/__init__.py
@@ -1367,12 +1367,20 @@ def _check_1d(x):
         return np.atleast_1d(x)
     else:
         try:
-            # work around https://github.com/pandas-dev/pandas/issues/27775
-            # which mean the shape is not as expected. That this ever worked
-            # was an unintentional quirk of pandas the above line will raise
-            # an exception in the future.
-            # This warns in pandas >= 1.0 via
+            # work around
+            # https://github.com/pandas-dev/pandas/issues/27775 which
+            # means the shape of multi-dimensional slicing is not as
+            # expected.  That this ever worked was an unintentional
+            # quirk of pandas and will raise an exception in the
+            # future.  This slicing warns in pandas >= 1.0rc0 via
             # https://github.com/pandas-dev/pandas/pull/30588
+            #
+            # < 1.0rc0 : x[:, None].ndim == 1, no warning, custom type
+            # >= 1.0rc1 : x[:, None].ndim == 2, warns, numpy array
+            # future : x[:, None] -> raises
+            #
+            # This code should correctly identify and coerce to a
+            # numpy array all pandas versions.
             with warnings.catch_warnings(record=True) as w:
                 warnings.filterwarnings("always",
                                         category=DeprecationWarning,
@@ -1381,8 +1389,11 @@ def _check_1d(x):
                 ndim = x[:, None].ndim
                 # we have definitely hit a pandas index or series object
                 # cast to a numpy array.
-                if len(w) != 0:
+                if len(w) > 0:
                     return np.asanyarray(x)
+            # We have likely hit a pandas object, or at least
+            # something where 2D slicing does not result in a 2D
+            # object.
             if ndim < 2:
                 return np.atleast_1d(x)
             return x
