Document Transform.__add__ and .__sub__.

anntzer · anntzer · commit fa5eec72dd59 · 2020-04-22T20:02:56.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
@@ -1341,23 +1341,24 @@ 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::
+        stack, and then ascends back up other's stack. If possible, identical
+        terms are cancelled::
 
-            # normally
-            A - B == a + b.inverted()
+            # In general:
+            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.
+            # If A "ends with" B (i.e. A == A' + B for some A') we can cancel
+            # out B:
+            (A' + B) - B == A'
 
-            (A + B) - (B)^-1 == A
+            # Likewise, if B "starts with" A (B = A + B'), we can cancel out A:
+            A - (A + B') == B'.inverted() == B'^-1
 
-            # 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)``.
+        Cancellation is important not only for performance, but also because 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.
         """
         # we only know how to do this operation if other is a Transform.
         if not isinstance(other, Transform):
