docs(api): new behavior for Labware.set_offset() in PAPI 2.18

api/src/opentrons/protocol_api/labware.py

@@ -577,22 +577,42 @@ def set_offset(self, x: float, y: float, z: float) -> None:
         """Set the labware's position offset.
 
         The offset is an x, y, z vector in deck coordinates
-        (see :ref:`protocol-api-deck-coords`) that the motion system
-        will add to any movement targeting this labware instance.
+        (see :ref:`protocol-api-deck-coords`).
 
-        The offset *will not apply* to any other labware instances,
-        even if those labware are of the same type.
+        How the motion system applies the offset depends on the API level of the protocol.
 
-        This method is *only* for use with mechanisms like
-        :obj:`opentrons.execute.get_protocol_api`, which lack an interactive way
-        to adjust labware offsets. (See :ref:`advanced-control`.)
+            - In API level 2.13 and earlier, it applies only to the labware instance it
+              is called on.
+            - In API levels 2.14–2.17, ``set_offset()`` is not available, and the API will
+              raise an error.
+            - In API level 2.18 and newer, the offset will apply to any labware of the
+              same type, in the same on-deck location. Labware type is defined as the
+              combination of the ``loadName``, ``namespace``, and ``version`` parameters
+              of :py:meth:`~.ProtocolContext.load_labware`.
 
-        .. warning::
+        For example, in API level 2.18, if you use ``set_offset()`` on a tip rack, use
+        all the tips, and replace the rack with a fresh one of the same type in the same
+        location, the offsets will apply to the fresh tip rack.
+
+        Furthermore, if you use ``set_offset()`` on a well plate and then use
+        :py:meth:`.move_labware` to change its location, the API will apply different
+        offsets for the new type–location combination. If you want to use the same
+        offsets in the new location, call ``set_offset()`` again, after the movement.
+
+        .. note::
 
-            If you're uploading a protocol via the Opentrons App, don't use this method,
-            because it will produce undefined behavior.
-            Instead, use Labware Position Check in the app or on the touchscreen.
+            Setting offsets with this method will override any labware offsets set
+            by running Labware Position Check in the Opentrons App.
+
+            This method is designed for use with mechanisms like
+            :obj:`opentrons.execute.get_protocol_api`, which lack an interactive way
+            to adjust labware offsets. (See :ref:`advanced-control`.)
+
+        .. versionchanged:: 2.14
+            Temporarily removed.
 
+        .. versionchanged:: 2.18
+            Restored, and now applies to labware type–location pairs.
         """
         if self._api_version >= ENGINE_CORE_API_VERSION:
             # TODO(mm, 2023-02-13): See Jira RCORE-535.