From c4941052f342091d390e9ba6639caa8011afb30d Mon Sep 17 00:00:00 2001
From: Max Marrone <max@opentrons.com>
Date: Mon, 14 Oct 2024 15:33:15 -0400
Subject: [PATCH] StateUpdate docstrings.

---
 .../protocol_engine/state/update_types.py     | 50 +++++++++++++------
 1 file changed, 36 insertions(+), 14 deletions(-)

diff --git a/api/src/opentrons/protocol_engine/state/update_types.py b/api/src/opentrons/protocol_engine/state/update_types.py
index 0bf00cfdd86..5d941d33933 100644
--- a/api/src/opentrons/protocol_engine/state/update_types.py
+++ b/api/src/opentrons/protocol_engine/state/update_types.py
@@ -66,9 +66,10 @@ class AddressableArea:
 
 @dataclasses.dataclass
 class PipetteLocationUpdate:
-    """Represents an update to perform on a pipette's location."""
+    """An update to a pipette's location."""
 
     pipette_id: str
+    """The ID of the already-loaded pipette."""
 
     new_location: Well | AddressableArea | None | NoChangeType
     """The pipette's new logical location.
@@ -82,19 +83,30 @@ class PipetteLocationUpdate:
 
 @dataclasses.dataclass
 class LabwareLocationUpdate:
-    """Represents an update to perform on a labware's location."""
+    """An update to a labware's location."""
 
     labware_id: str
+    """The ID of the already-loaded labware."""
 
     new_location: LabwareLocation
-    """The labware's new logical location."""
+    """The labware's new location."""
 
     offset_id: typing.Optional[str]
+    """The ID of the labware's new offset, for its new location."""
 
 
 @dataclasses.dataclass
-class LoadedLabwareUpdate(LabwareLocationUpdate):
-    """Update loaded labware."""
+class LoadedLabwareUpdate:
+    """An update that loads a new labware."""
+
+    labware_id: str
+    """The unique ID of the new labware."""
+
+    new_location: LabwareLocation
+    """The labware's initial location."""
+
+    offset_id: typing.Optional[str]
+    """The ID of the labware's offset."""
 
     display_name: typing.Optional[str]
 
@@ -103,9 +115,15 @@ class LoadedLabwareUpdate(LabwareLocationUpdate):
 
 @dataclasses.dataclass
 class LoadPipetteUpdate:
-    """Update loaded pipette."""
+    """An update that loads a new pipette.
+
+    NOTE: Currently, if this is provided, a PipetteConfigUpdate must always be
+    provided alongside it to fully initialize everything.
+    """
 
     pipette_id: str
+    """The unique ID of the new pipette."""
+
     pipette_name: PipetteNameType
     mount: MountType
     liquid_presence_detection: typing.Optional[bool]
@@ -113,10 +131,14 @@ class LoadPipetteUpdate:
 
 @dataclasses.dataclass
 class PipetteConfigUpdate:
-    """Update pipette config."""
+    """An update to a pipette's config."""
 
     pipette_id: str
+    """The ID of the already-loaded pipette."""
+
+    # todo(mm, 2024-10-14): Does serial_number belong in LoadPipetteUpdate?
     serial_number: str
+
     config: pipette_data_provider.LoadedStaticPipetteData
 
 
@@ -237,7 +259,7 @@ def set_labware_location(
         new_location: LabwareLocation,
         new_offset_id: str | None,
     ) -> None:
-        """Set labware location."""
+        """Set a labware's location. See `LabwareLocationUpdate`."""
         self.labware_location = LabwareLocationUpdate(
             labware_id=labware_id,
             new_location=new_location,
@@ -252,7 +274,7 @@ def set_loaded_labware(
         display_name: typing.Optional[str],
         location: LabwareLocation,
     ) -> None:
-        """Add loaded labware to state."""
+        """Add a new labware to state. See `LoadedLabwareUpdate`."""
         self.loaded_labware = LoadedLabwareUpdate(
             definition=definition,
             labware_id=labware_id,
@@ -268,7 +290,7 @@ def set_load_pipette(
         mount: MountType,
         liquid_presence_detection: typing.Optional[bool],
     ) -> None:
-        """Add loaded pipette to state."""
+        """Add a new pipette to state. See `LoadPipetteUpdate`."""
         self.loaded_pipette = LoadPipetteUpdate(
             pipette_id=pipette_id,
             pipette_name=pipette_name,
@@ -282,13 +304,13 @@ def update_pipette_config(
         config: pipette_data_provider.LoadedStaticPipetteData,
         serial_number: str,
     ) -> None:
-        """Update pipette config."""
+        """Update a pipette's config. See `PipetteConfigUpdate`."""
         self.pipette_config = PipetteConfigUpdate(
             pipette_id=pipette_id, config=config, serial_number=serial_number
         )
 
     def update_pipette_nozzle(self, pipette_id: str, nozzle_map: NozzleMap) -> None:
-        """Update pipette nozzle map."""
+        """Update a pipette's nozzle map. See `PipetteNozzleMapUpdate`."""
         self.pipette_nozzle_map = PipetteNozzleMapUpdate(
             pipette_id=pipette_id, nozzle_map=nozzle_map
         )
@@ -296,7 +318,7 @@ def update_pipette_nozzle(self, pipette_id: str, nozzle_map: NozzleMap) -> None:
     def update_pipette_tip_state(
         self, pipette_id: str, tip_geometry: typing.Optional[TipGeometry]
     ) -> None:
-        """Update tip state."""
+        """Update a pipette's tip state. See `PipetteTipStateUpdate`."""
         self.pipette_tip_state = PipetteTipStateUpdate(
             pipette_id=pipette_id, tip_geometry=tip_geometry
         )
@@ -304,7 +326,7 @@ def update_pipette_tip_state(
     def mark_tips_as_used(
         self, pipette_id: str, labware_id: str, well_name: str
     ) -> None:
-        """Mark tips in a tip rack as used. See `MarkTipsUsedState`."""
+        """Mark tips in a tip rack as used. See `TipsUsedUpdate`."""
         self.tips_used = TipsUsedUpdate(
             pipette_id=pipette_id, labware_id=labware_id, well_name=well_name
         )