polar: Clarify some of the documenting comments on transforms

Author: QuLogic

lib/matplotlib/projections/polar.py

@@ -839,8 +839,11 @@ def _init_axis(self):
         self.spines['polar'].register_axis(self.yaxis)
 
     def _set_lim_and_transforms(self):
-        # A view limit where the minimum radius can be locked if the user
-        # specifies an alternate origin.
+        # self.viewLim is set by the superclass and contains (θ, r) as its (x, y)
+        # components.
+
+        # This is a view limit (still in (θ, r) space) where the minimum radius can be
+        # locked if the user specifies an alternate origin.
         self._originViewLim = mtransforms.LockableBbox(self.viewLim)
 
         # Handle angular offset and direction.
@@ -849,83 +852,75 @@ def _set_lim_and_transforms(self):
         self._theta_offset = mtransforms.Affine2D() \
             .translate(self._default_theta_offset, 0.0)
         self.transShift = self._direction + self._theta_offset
-        # A view limit shifted to the correct location after accounting for
-        # orientation and offset.
-        self._realViewLim = mtransforms.TransformedBbox(self.viewLim,
-                                                        self.transShift)
-
-        # Transforms the x and y axis separately by a scale factor
-        # It is assumed that this part will have non-linear components
-        self.transScale = mtransforms.TransformWrapper(
-            mtransforms.IdentityTransform())
-
-        # Scale view limit into a bbox around the selected wedge. This may be
-        # smaller than the usual unit axes rectangle if not plotting the full
-        # circle.
-        self.axesLim = _WedgeBbox((0.5, 0.5),
-                                  self._realViewLim, self._originViewLim)
-
-        # Scale the wedge to fill the axes.
+        # This is a view limit in (θ, r) shifted to the correct location after
+        # accounting for θ orientation and offset.
+        self._realViewLim = mtransforms.TransformedBbox(self.viewLim, self.transShift)
+
+        # Transforms the θ and r axis separately by a scale factor. It is assumed that
+        # this part will have the non-linear components.
+        self.transScale = mtransforms.TransformWrapper(mtransforms.IdentityTransform())
+
+        # Scale view limit into a bbox around the selected wedge. This may be smaller
+        # than the usual unit axes rectangle if not plotting the full circle.
+        self.axesLim = _WedgeBbox((0.5, 0.5), self._realViewLim, self._originViewLim)
+
+        # Scale the wedge to fill the Axes unit space.
         self.transWedge = mtransforms.BboxTransformFrom(self.axesLim)
 
-        # Scale the axes to fill the figure.
+        # Scale the Axes unit space to fill the Axes actual position.
         self.transAxes = mtransforms.BboxTransformTo(self.bbox)
 
-        # A (possibly non-linear) projection on the (already scaled)
-        # data.  This one is aware of rmin
+        # A (possibly non-linear) projection on the (already scaled) data. This one is
+        # aware of rmin.
         self.transProjection = self.PolarTransform(
             self,
             scale_transform=self.transScale
         )
         # Add dependency on rorigin.
         self.transProjection.set_children(self._originViewLim)
 
-        # An affine transformation on the data, generally to limit the
-        # range of the axes
+        # An affine transformation on the data, generally to limit the range of the axes
         self.transProjectionAffine = self.PolarAffine(self.transScale,
                                                       self._originViewLim)
 
-        # The complete data transformation stack -- from data all the
-        # way to display coordinates
-        #
-        # 1. Remove any radial axis scaling (e.g. log scaling)
-        # 2. Shift data in the theta direction
-        # 3. Project the data from polar to cartesian values
-        #    (with the origin in the same place)
-        # 4. Scale and translate the cartesian values to Axes coordinates
-        #    (here the origin is moved to the lower left of the Axes)
-        # 5. Move and scale to fill the Axes
-        # 6. Convert from Axes coordinates to Figure coordinates
+        # The complete data transformation stack -- from data all the way to display
+        # coordinates.
         self.transData = (
+            # 1. Remove any radial axis scaling (e.g. log scaling).
             self.transScale +
+            # 2. Shift data in the θ direction.
             self.transShift +
+            # 3. Project the data from polar to cartesian values (with the origin in the
+            #    same place).
             self.transProjection +
             (
+                # 4. Scale and translate the cartesian values to Axes coordinates (here
+                #    the origin is moved to the lower left of the Axes).
                 self.transProjectionAffine +
+                # 5. Move and scale to fill the Axes.
                 self.transWedge +
+                # 6. Convert from Axes coordinates to Figure coordinates.
                 self.transAxes
             )
         )
 
-        # This is the transform for theta-axis ticks.  It is
-        # equivalent to transData, except it always puts r == 0.0 and r == 1.0
-        # at the edge of the axis circles.
+        # This is the transform for θ-axis ticks. It is equivalent to transData, except
+        # it always puts r == 0.0 and r == 1.0 at the edge of the axis circles.
         self._xaxis_transform = (
             mtransforms.blended_transform_factory(
                 mtransforms.IdentityTransform(),
                 mtransforms.BboxTransformTo(self.viewLim)) +
             self.transData)
-        # The theta labels are flipped along the radius, so that text 1 is on
-        # the outside by default. This should work the same as before.
+        # The θ labels are flipped along the radius, so that text 1 is on the outside by
+        # default. This should work the same as before.
         flipr_transform = mtransforms.Affine2D() \
             .translate(0.0, -0.5) \
             .scale(1.0, -1.0) \
             .translate(0.0, 0.5)
         self._xaxis_text_transform = flipr_transform + self._xaxis_transform
 
-        # This is the transform for r-axis ticks.  It scales the theta
-        # axis so the gridlines from 0.0 to 1.0, now go from thetamin to
-        # thetamax.
+        # This is the transform for r-axis ticks.  It scales the θ-axis so the gridlines
+        # from 0.0 to 1.0, now go from thetamin to thetamax.
         self._yaxis_transform = (
             mtransforms.blended_transform_factory(
                 mtransforms.BboxTransformTo(self.viewLim),