Comments and docstrings

scottshambaugh · scottshambaugh · commit 026802ac4a60 · 2022-07-21T21:49:48.000-06:00
diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py
@@ -872,9 +872,9 @@ def get_proj(self):
 
         # Calculate the viewing axes for the eye position
         u, v, n = self._calc_view_axes(eye)
-        self._view_u = u
-        self._view_v = v
-        self._view_n = n
+        self._view_u = u  # _view_u is towards the right of the screen
+        self._view_v = v  # _view_v is towards the top of the screen
+        self._view_n = n  # _view_n is out of the screen
 
         # Generate the view and projection transformation matrices
         if self._focal_length == np.inf:
@@ -1137,7 +1137,7 @@ def drag_pan(self, button, key, x, y):
 
     def _calc_view_axes(self, eye):
         """
-        Get the unit viewing axes in data coordinates.
+        Get the unit vectors for the viewing axes in data coordinates.
         `u` is towards the right of the screen
         `v` is towards the top of the screen
         `n` is out of the screen
@@ -1186,31 +1186,32 @@ def _set_view_from_bbox(self, bbox, direction='in',
         # Calculate zoom level
         dx = abs(start_x - stop_x)
         dy = abs(start_y - stop_y)
-        scale_x = dx / (self.bbox.max[0] - self.bbox.min[0])
-        scale_y = dy / (self.bbox.max[1] - self.bbox.min[1])
-        scale_z = 1
+        scale_u = dx / (self.bbox.max[0] - self.bbox.min[0])
+        scale_v = dy / (self.bbox.max[1] - self.bbox.min[1])
+        scale_n = 1
 
         # Limit box zoom to reasonable range, protect for divide by zero below
-        scale_x = np.clip(scale_x, 1e-2, 1e2)
-        scale_y = np.clip(scale_y, 1e-2, 1e2)
+        scale_u = np.clip(scale_u, 1e-2, 1e2)
+        scale_v = np.clip(scale_v, 1e-2, 1e2)
 
         if direction == 'out':
-            scale_x = 1 / scale_x
-            scale_y = 1 / scale_y
+            scale_u = 1 / scale_u
+            scale_v = 1 / scale_v
 
-        self._zoom_data_limits(scale_x, scale_y, scale_z)
+        self._zoom_data_limits(scale_u, scale_v, scale_v)
 
-    def _zoom_data_limits(self, scale_x, scale_y, scale_z):
+    def _zoom_data_limits(self, scale_u, scale_v, scale_n):
         """
         Zoom in or out of a 3D plot.
-        Will scale the data limits by the scale factors, where scale_x,
-        scale_y, and scale_z refer to the scale factors for the viewing axes.
-        These will be transformed to the data axes based on the current view
-        angles. A scale factor > 1 zooms out and a scale factor < 1 zooms in.
+        Will scale the data limits by the scale factors, where scale_u,
+        scale_v, and scale_n refer to the scale factors for the viewing axes.
+        These will be transformed to the x, y, z data axes based on the current
+        view angles. A scale factor > 1 zooms out and a scale factor < 1 zooms
+        in.
         """
         # Convert from the scale factors in the view frame to the data frame
         R = np.array([self._view_u, self._view_v, self._view_n])
-        S = np.array([scale_x, scale_y, scale_z])
+        S = np.array([scale_u, scale_v, scale_n])
         scale = np.linalg.norm(R.T@(np.eye(3)*S), axis=1)
 
         # Scale the data range
@@ -1376,7 +1377,7 @@ def plot(self, xs, ys, *args, zdir='z', **kwargs):
             z coordinates of vertices; either one for all points or one for
             each point.
         zdir : {'x', 'y', 'z'}, default: 'z'
-            When plotting 3D data, the direction to use as z ('x', 'y' or 'z').
+            When plotting 2D data, the direction to use as z ('x', 'y' or 'z').
         **kwargs
             Other arguments are forwarded to `matplotlib.axes.Axes.plot`.
         """
