Single line summaries of docstrings

src/openflexure_microscope_server/things/camera/__init__.py

@@ -156,8 +156,10 @@ class BaseCamera(lt.Thing):
     def start_streaming(
         self, main_resolution: tuple[int, int], buffer_count: int
     ) -> None:
-        """Start (or stop and restart) the camera with the given resolution
-        for the main stream, and buffer_count number of images in the buffer
+        """Start (or stop and restart) the camera.
+
+        :param main_resolution: the resolution to use for the main stream.
+        :param buffer_count: number of images in the stream buffer.
         """
         raise NotImplementedError(
             "CameraThings must define their own start_streaming method"
@@ -342,12 +344,14 @@ class BaseCamera(lt.Thing):
         metadata_getter: lt.deps.GetThingStates,
         logger: lt.deps.InvocationLogger,
     ) -> Image:
-        """Capture an image in memory and return it with metadata
-        CaptureError raised if the capture fails for any reason
-        returns tuple with PIL Image, and dict of metadata.
+        """Capture an image in memory and return it with metadata.
 
         This robust capturing method attempts to capture the image five times
         each time with a 5 second timeout set.
+
+        :raises CaptureError: if the capture fails for any reason
+
+        :returns: tuple with PIL Image, and dictionary of metadata.
         """
         for capture_attempts in range(5):
             try:

src/openflexure_microscope_server/things/camera/picamera.py

@@ -62,8 +62,9 @@ class PicameraStreamOutput(Output):
 
 
 class SensorMode(BaseModel):
-    """A Pydantic model holding all the information about a specific
-    sensor mode as reported by the PiCamera.
+    """A Pydantic model holding all the information about a specific sensor mode.
+
+    This data is as reported by the PiCamera2 module.
     """
 
     unpacked: str
@@ -76,10 +77,11 @@ class SensorMode(BaseModel):
 
 
 class SensorModeSelector(BaseModel):
-    """A Pydantic model holding the two values needed to select a PiCamera
-    Sensor mode. The output size and the bit depth.
+    """A Pydantic model holding the two values needed to select a PiCamera Sensor mode.
 
-    This is a Pydantic modell so that it can be saved to the disk.
+    Theses values are the output size and the bit depth.
+
+    This is a Pydantic model so that it can be saved to disk.
     """
 
     output_size: tuple[int, int]

src/openflexure_microscope_server/things/camera/picamera_recalibrate_utils.py

@@ -477,12 +477,16 @@ def set_static_geq(
     tuning: dict,
     offset: int = 65535,
 ) -> None:
-    """Update the ``rpi.geq`` section of a camera tuning dict to always use green
-    equalisation that averages the green pixels in the red and blue rows.
+    """Update the ``rpi.geq`` section of a camera tuning dict.
 
-    ``tuning`` will be updated in-place to set the geq offest to the given value.
-    The default 65535 is the maximum allowed value. This means
-    the brightness will always be below the threshold where averaging is used.
+    :param tuning: the raspberry pi tuning file. This will be updated in-place to
+        set the geq offest to the given value.
+    :param offset: The desired green equalisation offset. Default 65535. The default is
+        the maximum allowed value. This means the brightness will always be below the
+        threshold where averaging is used. This is default as we always need the green
+        equalisation to averages the green pixels in the red and blue rows due to the
+        chief ray angle compensation issue when the the stock lens is replaced by an
+        objective.
     """
     geq = Picamera2.find_tuning_algo(tuning, "rpi.geq")
     geq["offset"] = offset  # max out offset to disable the adaptive green equalisation