From abf236a046ec37cc3845104be552aea707b57c99 Mon Sep 17 00:00:00 2001
From: jan <jan@orange.mpxd.net>
Date: Sun, 15 Feb 2026 19:46:47 -0800
Subject: [PATCH] [mirror / flip_across] improve documentation

---
 masque/label.py             |  6 ++++--
 masque/ports.py             |  4 +++-
 masque/traits/mirrorable.py | 14 +++++++++++---
 3 files changed, 18 insertions(+), 6 deletions(-)

diff --git a/masque/label.py b/masque/label.py
index 4bd2c4a..8b67c65 100644
--- a/masque/label.py
+++ b/masque/label.py
@@ -104,10 +104,12 @@ class Label(PositionableImpl, RepeatableImpl, AnnotatableImpl, Bounded, Pivotabl
 
     def flip_across(self, axis: int | None = None, *, x: float | None = None, y: float | None = None) -> Self:
         """
-        Mirror the object across a line.
+        Flip the label across a line in the pattern's coordinate system.
+
+        This operation mirrors the label's offset relative to the pattern's origin.
 
         Args:
-            axis: Axis to mirror across. 0 mirrors across x=0. 1 mirrors across y=0.
+            axis: Axis to mirror across. 0 mirrors across y=0. 1 mirrors across x=0.
             x: Vertical line x=val to mirror across.
             y: Horizontal line y=val to mirror across.
 
diff --git a/masque/ports.py b/masque/ports.py
index c40cf55..45aedb5 100644
--- a/masque/ports.py
+++ b/masque/ports.py
@@ -108,7 +108,9 @@ class Port(PivotableImpl, PositionableImpl, Mirrorable, Flippable, Copyable):
 
     def flip_across(self, axis: int | None = None, *, x: float | None = None, y: float | None = None) -> Self:
         """
-        Mirror the object across a line.
+        Mirror the object across a line in the container's coordinate system.
+
+        Note this operation is performed relative to the pattern's origin and modifies the port's offset.
 
         Args:
             axis: Axis to mirror across. 0 mirrors across y=0. 1 mirrors across x=0.
diff --git a/masque/traits/mirrorable.py b/masque/traits/mirrorable.py
index 644db61..deddddd 100644
--- a/masque/traits/mirrorable.py
+++ b/masque/traits/mirrorable.py
@@ -18,7 +18,11 @@ class Mirrorable(metaclass=ABCMeta):
     @abstractmethod
     def mirror(self, axis: int = 0) -> Self:
         """
-        Mirror the entity across an axis through its origin, ignoring its offset.
+        Mirror the entity across an axis through its origin.
+
+        This operation is performed relative to the object's internal origin (ignoring
+        its offset). For objects like `Polygon` and `Path` where the offset is forced
+        to (0, 0), this is equivalent to mirroring in the container's coordinate system.
 
         Args:
             axis: Axis to mirror across (0: x-axis, 1: y-axis).
@@ -70,10 +74,14 @@ class Flippable(Positionable, metaclass=ABCMeta):
     @abstractmethod
     def flip_across(self, axis: int | None = None, *, x: float | None = None, y: float | None = None) -> Self:
         """
-        Mirror the object across a line.
+        Mirror the object across a line in the container's coordinate system.
+
+        Unlike `mirror()`, this operation is performed relative to the container's origin
+        (e.g. the `Pattern` origin, in the case of shapes) and takes the object's offset
+        into account.
 
         Args:
-            axis: Axis to mirror across. 0 mirrors across x=0. 1 mirrors across y=0.
+            axis: Axis to mirror across. 0 mirrors across y=0. 1 mirrors across x=0.
             x: Vertical line x=val to mirror across.
             y: Horizontal line y=val to mirror across.