Scale frontend: correct deprecation path, add docstrings and return type annotations

pylabrobot/scales/scale.py

@@ -1,3 +1,6 @@
+"""Frontend for analytical scales (zero, tare, read weight)."""
+
+import warnings
 from typing import Optional
 
 from pylabrobot.machines.machine import Machine
@@ -32,14 +35,44 @@ def __init__(
     )
     self.backend: ScaleBackend = backend  # fix type
 
-  async def tare(self, **backend_kwargs):
-    """Tare the scale"""
-    await self.backend.tare(**backend_kwargs)
+  async def zero(self, **backend_kwargs) -> None:
+    """Calibrate the scale's zero point to the current load.
 
-  async def zero(self, **backend_kwargs):
-    """Zero the scale"""
+    Establishes the baseline "empty" reading. Unlike tare, this
+    does not account for container weight - it simply resets what
+    the scale considers zero. Does not restore scale capacity.
+    """
     await self.backend.zero(**backend_kwargs)
 
+  async def tare(self, **backend_kwargs) -> None:
+    """Reset the displayed weight to zero, storing the current
+    weight as the tare value.
+
+    Use this to measure only the weight of material added after
+    taring (e.g. ignoring a container).
+    Note: taring does not restore scale capacity.
+    """
+    await self.backend.tare(**backend_kwargs)
+
+  async def read_weight(self, **backend_kwargs) -> float:
+    """Read the current weight in grams.
+
+    The scale may take a moment to stabilize after loading.
+    Use the ``timeout`` backend kwarg to control stability
+    behavior: ``"stable"`` waits for a settled reading, ``0`` returns
+    immediately, or pass a number of seconds to wait at most that long.
+    """
+    return await self.backend.read_weight(**backend_kwargs)
+
+  # # # Deprecated # # #
+  # TODO: remove after 2026-06
+
   async def get_weight(self, **backend_kwargs) -> float:
-    """Get the weight in grams"""
-    return await self.backend.get_weight(**backend_kwargs)
+    """Deprecated: use :meth:`read_weight` instead."""
+    warnings.warn(
+      "scale.get_weight() is deprecated and will be removed in 2026-06. "
+      "Use scale.read_weight() instead.",
+      DeprecationWarning,
+      stacklevel=2,
+    )
+    return await self.backend.read_weight(**backend_kwargs)