Warn when passing triangles or mask alongside a Triangulation

timhoffm · timhoffm · commit 39cfe2b94eb4 · 2022-01-29T21:35:32.000+01:00
diff --git a/lib/matplotlib/tri/triangulation.py b/lib/matplotlib/tri/triangulation.py
@@ -1,5 +1,7 @@
 import numpy as np
 
+from matplotlib import _api
+
 
 class Triangulation:
     """
@@ -135,6 +137,14 @@ def get_from_args_and_kwargs(*args, **kwargs):
         """
         if isinstance(args[0], Triangulation):
             triangulation, *args = args
+            if 'triangles' in kwargs:
+                _api.warn_external(
+                    "Passing the keyword 'triangles' has no effect when also "
+                    "passing a Triangulation")
+            if 'mask' in kwargs:
+                _api.warn_external(
+                    "Passing the keyword 'mask' has no effect when also "
+                    "passing a Triangulation")
         else:
             x, y, triangles, mask, args, kwargs = \
                 Triangulation._extract_triangulation_params(args, kwargs)
diff --git a/lib/matplotlib/tri/tripcolor.py b/lib/matplotlib/tri/tripcolor.py
@@ -11,22 +11,24 @@ def tripcolor(ax, *args, alpha=1.0, norm=None, cmap=None, vmin=None,
     """
     Create a pseudocolor plot of an unstructured triangular grid.
 
-    The triangulation can be specified in one of two ways; either::
+    Call signatures::
 
-      tripcolor(triangulation, ...)
+      tripcolor(triangulation, C, *, ...)
+      tripcolor(x, y, C, *, [triangles=triangles], [mask=mask], ...)
 
-    where triangulation is a `.Triangulation` object, or
+    The triangular grid can be specified either by passing a `.Triangulation`
+    object as the first parameter, or by passing the points *x*, *y* and
+    optionally the *triangles* and a *mask*. See `.Triangulation` for an
+    explanation of these parameters.
 
-    ::
+    Parameters
+    ----------
+    triangulation : `.Triangulation`
+        An already created triangular grid.
+    x, y, triangles, mask
+        Parameters specifying defining the triangular grid. See
+        `.Triangulation`.
 
-      tripcolor(x, y, ...)
-      tripcolor(x, y, triangles, ...)
-      tripcolor(x, y, triangles=triangles, ...)
-      tripcolor(x, y, mask=mask, ...)
-      tripcolor(x, y, triangles, mask=mask, ...)
-
-    in which case a Triangulation object will be created.  See `.Triangulation`
-    for a explanation of these possibilities.
 
     The next argument must be *C*, the array of color values, either
     one per point in the triangulation if color values are defined at
@@ -42,6 +44,11 @@ def tripcolor(ax, *args, alpha=1.0, norm=None, cmap=None, vmin=None,
     three points. If *shading* is 'gouraud' then color values must be
     defined at points.
 
+
+
+    tripcolor(x, y, [triangles], C, [mask=mask], ...)
+
+
     The remaining kwargs are the same as for `~.Axes.pcolor`.
     """
     _api.check_in_list(['flat', 'gouraud'], shading=shading)
