Document Transform.__add__ and .__sub__.

anntzer · anntzer · commit ad525ab07219 · 2020-04-22T21:44:29.000+02:00
diff --git a/doc/api/transformations.rst b/doc/api/transformations.rst
@@ -14,4 +14,5 @@
        BboxTransformFrom, ScaledTranslation, TransformedPath, nonsingular,
        interval_contains, interval_contains_open
    :show-inheritance:
+   :special-members:
 
diff --git a/lib/matplotlib/transforms.py b/lib/matplotlib/transforms.py
@@ -1340,24 +1340,32 @@ def contains_branch_seperately(self, other_transform):
 
     def __sub__(self, other):
         """
-        Return a transform stack which goes all the way down self's transform
-        stack, and then ascends back up other's stack. If it can, this is
-        optimised::
-
-            # normally
-            A - B == a + b.inverted()
-
-            # sometimes, when A contains the tree B there is no need to
-            # descend all the way down to the base of A (via B), instead we
-            # can just stop at B.
-
-            (A + B) - (B)^-1 == A
-
-            # similarly, when B contains tree A, we can avoid descending A at
-            # all, basically:
-            A - (A + B) == ((B + A) - A).inverted() or B^-1
-
-        For clarity, the result of ``(A + B) - B + B == (A + B)``.
+        Compose *self* with the inverse of *other*, cancelling identical terms
+        if any::
+
+            # In general:
+            A - B == A + B.inverted()
+            # (but see note regarding frozen transforms below).
+
+            # If A "ends with" B (i.e. A == A' + B for some A') we can cancel
+            # out B:
+            (A' + B) - B == A'
+
+            # Likewise, if B "starts with" A (B = A + B'), we can cancel out A:
+            A - (A + B') == B'.inverted() == B'^-1
+
+        Cancellation (rather than naively returning ``A + B.inverted()``) is
+        important for multiple reasons:
+
+        - It avoids floating-point inaccuracies when computing the inverse of
+          B: ``B - B`` is guaranteed to cancel out exactly (resulting in the
+          identity transform), whereas ``B + B.inverted()`` may differ by a
+          small epsilon.
+        - ``B.inverted()`` always returns a frozen transform: if one computes
+          ``A + B + B.inverted()`` and later mutates ``B``, then
+          ``B.inverted()`` won't be updated and the last two terms won't cancel
+          out anymore; on the other hand, ``A + B - B`` will always be equal to
+          ``A`` even if ``B`` is mutated.
         """
         # we only know how to do this operation if other is a Transform.
         if not isinstance(other, Transform):
