233 fix docstrings

src/ephys_link/common.py

@@ -14,9 +14,9 @@
 
 
 def dprint(message: str) -> None:
-    """Print message if debug is enabled
+    """Print message if debug is enabled.
 
-    :param message: Message to print
+    :param message: Message to print.
     :type message: str
     :return: None
     """
@@ -26,30 +26,60 @@ def dprint(message: str) -> None:
 
 # Input data formats
 class GotoPositionInputDataFormat(TypedDict):
-    """Data format for :func:`server.goto_pos`"""
+    """Data format for positional requests.
+
+    :param manipulator_id: ID of the manipulator to move.
+    :type manipulator_id: str
+    :param pos: Position to move to in mm (X, Y, Z, W).
+    :type pos: list[float]
+    :param speed: Speed to move at in mm/s.
+    :type speed: float
+    """
 
     manipulator_id: str
     pos: list[float]
-    speed: int
+    speed: float
 
 
 class InsideBrainInputDataFormat(TypedDict):
-    """Data format for :func:`server.set_inside_brain`"""
+    """Data format for setting inside brain state.
+
+    :param manipulator_id: ID of the manipulator to move.
+    :type manipulator_id: str
+    :param inside: Whether the manipulator is inside the brain.
+    :type inside: bool
+    """
 
     manipulator_id: str
     inside: bool
 
 
 class DriveToDepthInputDataFormat(TypedDict):
-    """Data format for :func:`server.drive_to_depth`"""
+    """Data format for depth driving requests.
+
+    :param manipulator_id: ID of the manipulator to move.
+    :type manipulator_id: str
+    :param depth: Depth to drive to in mm.
+    :type depth: float
+    :param speed: Speed to drive at in mm/s.
+    :type speed: float
+    """
 
     manipulator_id: str
     depth: float
-    speed: int
+    speed: float
 
 
 class CanWriteInputDataFormat(TypedDict):
-    """Data format for :func:`server.set_can_write`"""
+    """Data format for setting can write state.
+
+    :param manipulator_id: ID of the manipulator to move.
+    :type manipulator_id: str
+    :param can_write: Whether the manipulator can write.
+    :type can_write: bool
+    :param hours: Number of hours the manipulator can write for.
+    :type hours: float
+    """
 
     manipulator_id: str
     can_write: bool
@@ -58,19 +88,19 @@ class CanWriteInputDataFormat(TypedDict):
 
 # Output data dictionaries
 class GetManipulatorsOutputData(dict):
-    """Output format for (manipulators)
+    """Output format for get manipulators request.
 
-    :param manipulators: Tuple of manipulator IDs (as strings)
+    :param manipulators: List of manipulator IDs (as strings).
     :type manipulators: list
-    :param num_axes: Number of axes this manipulator has
+    :param num_axes: Number of axes this manipulator has.
     :type num_axes: int
-    :param dimensions: Size of the movement space in mm (first 3 axes)
+    :param dimensions: Size of the movement space in mm (first 3 axes).
     :type dimensions: list
-    :param error: Error message
+    :param error: Error message.
     :type error: str
 
     :example: Example generated dictionary
-        :code:`{"manipulators": ["1", "2"], "error": ""}`
+        :code:`{"manipulators": ["1", "2"], "num_axes": 4, "dimensions": [20, 20, 20], "error": ""}`
     """
 
     def __init__(self, manipulators: list, num_axes: int, dimensions: list, error: str) -> None:
@@ -88,11 +118,11 @@ def json(self) -> str:
 
 
 class PositionalOutputData(dict):
-    """Output format for (position, error)
+    """Output format for positional requests.
 
-    :param position: Position in mm (as a tuple, can be empty) in X, Y, Z, W order
+    :param position: Position in mm (as a list, empty on error) in X, Y, Z, W order.
     :type position: list
-    :param error: Error message
+    :param error: Error message.
     :type error: str
 
     :example: Example generated dictionary
@@ -109,11 +139,11 @@ def json(self) -> str:
 
 
 class AngularOutputData(dict):
-    """Output format for (angles, error)
+    """Output format for manipulator angle requests.
 
-    :param angles: Angles in degrees (as a tuple, can be empty) in yaw, pitch, roll order
+    :param angles: Angles in degrees (as a list, can be empty) in yaw, pitch, roll order.
     :type angles: list
-    :param error: Error message
+    :param error: Error message.
     :type error: str
     """
 
@@ -127,11 +157,11 @@ def json(self) -> str:
 
 
 class ShankCountOutputData(dict):
-    """Output format for (num_shanks, error)
+    """Output format for number of shanks.
 
-    :param shank_count: Number of shanks on the probe
+    :param shank_count: Number of shanks on the probe (-1 if error).
     :type shank_count: int
-    :param error: Error message
+    :param error: Error message.
     :type error: str
     """
 
@@ -145,14 +175,14 @@ def json(self) -> str:
 
 
 class DriveToDepthOutputData(dict):
-    """Output format for depth driving (depth, error)
+    """Output format for depth driving.
 
-    :param depth: Depth in mm
+    :param depth: Depth in mm (0 on error).
     :type depth: float
-    :param error: Error message
+    :param error: Error message.
     :type error: str
 
-    :example: Example generated dictionary :code:`{"depth": 0.123, "error": ""}`
+    :example: Example generated dictionary :code:`{"depth": 1.23, "error": ""}`
     """
 
     def __init__(self, depth: float, error: str) -> None:
@@ -165,11 +195,11 @@ def json(self) -> str:
 
 
 class StateOutputData(dict):
-    """Output format for (state, error)
+    """Output format for boolean state requests.
 
-    :param state: State of the event
+    :param state: State of the event.
     :type state: bool
-    :param error: Error message
+    :param error: Error message.
     :type error: str
 
     :example: Example generated dictionary :code:`{"state": True, "error": ""}`