From af1eb5ce7c64ec3e033f08397f412ca51931765c Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Tue, 3 Mar 2020 18:01:35 +0100
Subject: [PATCH] Document filling of Poly3DCollection

---
 lib/mpl_toolkits/mplot3d/art3d.py | 34 +++++++++++++++++++++++++------
 1 file changed, 28 insertions(+), 6 deletions(-)

diff --git a/lib/mpl_toolkits/mplot3d/art3d.py b/lib/mpl_toolkits/mplot3d/art3d.py
index 76bdf35b0657..206641e5814f 100644
--- a/lib/mpl_toolkits/mplot3d/art3d.py
+++ b/lib/mpl_toolkits/mplot3d/art3d.py
@@ -530,17 +530,39 @@ def patch_collection_2d_to_3d(col, zs=0, zdir='z', depthshade=True):
 class Poly3DCollection(PolyCollection):
     """
     A collection of 3D polygons.
+
+    .. note::
+        **Filling of 3D polygons**
+
+        There is no simple definition of the enclosed surface of a 3D polygon
+        unless the polygon is planar.
+
+        In practice, Matplotlib performs the filling on the 2D projection of
+        the polygon. This gives a correct filling appearance only for planar
+        polygons. For all other polygons, you'll find orientations in which
+        the edges of the polygon intersect in the projection. This will lead
+        to an incorrect visualization of the 3D area.
+
+        If you need filled areas, it is recommended to create them via
+        `~mpl_toolkits.mplot3d.axes3d.Axes3D.plot_trisurf`, which creates a
+        triangulation and thus generates consistent surfaces.
     """
 
     def __init__(self, verts, *args, zsort='average', **kwargs):
         """
-        Create a Poly3DCollection.
-
-        *verts* should contain 3D coordinates.
-
-        Keyword arguments:
-        zsort, see set_zsort for options.
+        Parameters
+        ----------
+        verts : list of array-like Nx3
+            Each element describes a polygon as a sequnce of ``N_i`` points
+            ``(x, y, z)``.
+        zsort : {'average', 'min', 'max'}, default: 'average'
+            The calculation method for the z-order.
+            See `~.Poly3DCollection.set_zsort` for details.
+        *args, **kwargs
+            All other parameters are forwarded to `.PolyCollection`.
 
+        Notes
+        -----
         Note that this class does a bit of magic with the _facecolors
         and _edgecolors properties.
         """