Merge pull request matplotlib#27519 from oscargus/3ddocs

[Doc] Improve/correct docs for 3D

Author: timhoffm

lib/mpl_toolkits/mplot3d/art3d.py

@@ -826,14 +826,17 @@ def patch_collection_2d_to_3d(col, zs=0, zdir='z', depthshade=True):
 
     Parameters
     ----------
+    col : `~matplotlib.collections.PatchCollection` or \
+`~matplotlib.collections.PathCollection`
+        The collection to convert.
     zs : float or array of floats
         The location or locations to place the patches in the collection along
         the *zdir* axis. Default: 0.
     zdir : {'x', 'y', 'z'}
         The axis in which to place the patches. Default: "z".
         See `.get_dir_vector` for a description of the values.
-    depthshade
-        Whether to shade the patches to give a sense of depth. Default: *True*.
+    depthshade : bool, default: True
+        Whether to shade the patches to give a sense of depth.
 
     """
     if isinstance(col, PathCollection):
@@ -1117,6 +1120,8 @@ def poly_collection_2d_to_3d(col, zs=0, zdir='z'):
 
     Parameters
     ----------
+    col : `~matplotlib.collections.PolyCollection`
+        The collection to convert.
     zs : float or array of floats
         The location or locations to place the polygons in the collection along
         the *zdir* axis. Default: 0.

lib/mpl_toolkits/mplot3d/axes3d.py

@@ -1880,7 +1880,7 @@ def plot(self, xs, ys, *args, zdir='z', **kwargs):
         if args and not isinstance(args[0], str):
             zs, *args = args
             if 'zs' in kwargs:
-                raise TypeError("plot() for multiple values for argument 'z'")
+                raise TypeError("plot() for multiple values for argument 'zs'")
         else:
             zs = kwargs.pop('zs', 0)
 
@@ -1943,23 +1943,23 @@ def plot_surface(self, X, Y, Z, *, norm=None, vmin=None,
         color : color-like
             Color of the surface patches.
 
-        cmap : Colormap
+        cmap : Colormap, optional
             Colormap of the surface patches.
 
-        facecolors : array-like of colors.
+        facecolors : array-like of colors
             Colors of each individual patch.
 
-        norm : Normalize
+        norm : `~matplotlib.colors.Normalize`, optional
             Normalization for the colormap.
 
-        vmin, vmax : float
+        vmin, vmax : float, optional
             Bounds for the normalization.
 
         shade : bool, default: True
             Whether to shade the facecolors.  Shading is always disabled when
             *cmap* is specified.
 
-        lightsource : `~matplotlib.colors.LightSource`
+        lightsource : `~matplotlib.colors.LightSource`, optional
             The lightsource to use when *shade* is True.
 
         **kwargs
@@ -2242,14 +2242,14 @@ def plot_trisurf(self, *args, color=None, norm=None, vmin=None, vmax=None,
             Color of the surface patches.
         cmap
             A colormap for the surface patches.
-        norm : Normalize
+        norm : `~matplotlib.colors.Normalize`, optional
             An instance of Normalize to map values to colors.
-        vmin, vmax : float, default: None
+        vmin, vmax : float, optional
             Minimum and maximum value to map.
         shade : bool, default: True
             Whether to shade the facecolors.  Shading is always disabled when
             *cmap* is specified.
-        lightsource : `~matplotlib.colors.LightSource`
+        lightsource : `~matplotlib.colors.LightSource`, optional
             The lightsource to use when *shade* is True.
         **kwargs
             All other keyword arguments are passed on to
@@ -2379,7 +2379,7 @@ def contour(self, X, Y, Z, *args,
             Input data. See `.Axes.contour` for supported data shapes.
         extend3d : bool, default: False
             Whether to extend contour in 3D.
-        stride : int
+        stride : int, default: 5
             Step size for extending contour.
         zdir : {'x', 'y', 'z'}, default: 'z'
             The direction to use.
@@ -2423,7 +2423,7 @@ def tricontour(self, *args,
             Input data. See `.Axes.tricontour` for supported data shapes.
         extend3d : bool, default: False
             Whether to extend contour in 3D.
-        stride : int
+        stride : int, default: 5
             Step size for extending contour.
         zdir : {'x', 'y', 'z'}, default: 'z'
             The direction to use.
@@ -2558,13 +2558,14 @@ def add_collection3d(self, col, zs=0, zdir='z'):
         Add a 3D collection object to the plot.
 
         2D collection types are converted to a 3D version by
-        modifying the object and adding z coordinate information.
+        modifying the object and adding z coordinate information,
+        *zs* and *zdir*.
 
-        Supported are:
+        Supported 2D collection types are:
 
-        - PolyCollection
-        - LineCollection
-        - PatchCollection
+        - `.PolyCollection`
+        - `.LineCollection`
+        - `.PatchCollection`
         """
         zvals = np.atleast_1d(zs)
         zsortval = (np.min(zvals) if zvals.size
@@ -2676,7 +2677,7 @@ def bar(self, left, height, zs=0, zdir='z', *args, **kwargs):
             The x coordinates of the left sides of the bars.
         height : 1D array-like
             The height of the bars.
-        zs : float or 1D array-like
+        zs : float or 1D array-like, default: 0
             Z coordinate of bars; if a single value is specified, it will be
             used for all bars.
         zdir : {'x', 'y', 'z'}, default: 'z'
@@ -2759,14 +2760,14 @@ def bar3d(self, x, y, z, dx, dy, dz, color=None,
             5. -X
             6. +X
 
-        zsort : str, optional
+        zsort : {'average', 'min', 'max'}, default: 'average'
             The z-axis sorting scheme passed onto `~.art3d.Poly3DCollection`
 
         shade : bool, default: True
             When true, this shades the dark sides of the bars (relative
             to the plot's source of light).
 
-        lightsource : `~matplotlib.colors.LightSource`
+        lightsource : `~matplotlib.colors.LightSource`, optional
             The lightsource to use when *shade* is True.
 
         data : indexable object, optional
@@ -3063,7 +3064,7 @@ def voxels(self, *args, facecolors=None, edgecolors=None, shade=True,
         shade : bool, default: True
             Whether to shade the facecolors.
 
-        lightsource : `~matplotlib.colors.LightSource`
+        lightsource : `~matplotlib.colors.LightSource`, optional
             The lightsource to use when *shade* is True.
 
         **kwargs