Add docstrings to public methods

pyproject.toml

@@ -129,7 +129,6 @@ ignore = [
     "D213",  # incompatible with D212
     "D400",  # A stricter version of #415 that doesn't allow !
     # The checkers below should be turned on as they complain about missing docstrings.
-    "D102",
     "D103",
     "D104",
     "D105",

src/openflexure_microscope_server/things/autofocus.py

@@ -235,6 +235,16 @@ class JPEGSharpnessMonitor:
             self.running = False
 
     def focus_rel(self, dz: int, **kwargs) -> tuple[int, int]:
+        """Move the stage by dz, monitoring the position over time.
+
+        This performs exactly one move. Multiple calls of this method
+        will append to the internal postition storage for more complex
+        autofocus procedures.
+
+        This should be run from within the JPEGSharpnessMonitor.run
+        context manager so that sharpness data and timestamps are also
+        collected.
+        """
         # Store the start time and position
         self.stage_times.append(time.time())
         self.stage_positions.append(self.stage.position)

src/openflexure_microscope_server/things/background_detect.py

@@ -154,6 +154,7 @@ class BackgroundDetectThing(lt.Thing):
 
     @property
     def thing_state(self) -> Mapping:
+        """Summary metadata describing the current state of the Thing."""
         bd = self.background_distributions
         return {
             "background_distributions": bd.model_dump() if bd else None,

src/openflexure_microscope_server/things/camera/__init__.py

@@ -194,6 +194,7 @@ class BaseCamera(lt.Thing):
         stream_name: Literal["main", "lores", "raw", "full"] = "main",
         wait: Optional[float] = 5,
     ) -> NDArray:
+        """Acquire one image from the camera and return as an array."""
         raise NotImplementedError(
             "CameraThings must define their own capture_array method"
         )

src/openflexure_microscope_server/things/camera/picamera.py

@@ -166,6 +166,7 @@ class StreamingPiCamera2(BaseCamera):
 
     @lt.thing_setting
     def analogue_gain(self) -> float:
+        """The Analogue gain applied by the camera sensor."""
         if not self._setting_save_in_progress and self.streaming:
             with self._streaming_picamera() as cam:
                 cam_value = cam.capture_metadata()["AnalogueGain"]
@@ -185,6 +186,7 @@ class StreamingPiCamera2(BaseCamera):
 
     @lt.thing_setting
     def colour_gains(self) -> tuple[float, float]:
+        """The red and blue colour gains, must be betwen 0.0 and 32.0."""
         if not self._setting_save_in_progress and self.streaming:
             with self._streaming_picamera() as cam:
                 cam_value = cam.capture_metadata()["ColourGains"]
@@ -204,6 +206,11 @@ class StreamingPiCamera2(BaseCamera):
 
     @lt.thing_setting
     def exposure_time(self) -> int:
+        """The camera exposure time in microseconds.
+
+        When setting this property the camera will adjust the set value
+        to the nearest allowed value that is lower than the current setting.
+        """
         if not self._setting_save_in_progress and self.streaming:
             with self._streaming_picamera() as cam:
                 cam_value = cam.capture_metadata()["ExposureTime"]

src/openflexure_microscope_server/things/camera/simulation.py

@@ -115,10 +115,20 @@ class SimulatedCamera(BaseCamera):
     def attach_to_server(
         self, server: lt.ThingServer, path: str, setting_storage_path: str
     ):
+        """Wrap the attach_to_server method so the server instance can be stored.
+
+        Direct access to the server instance is needed to get the stage position while
+        maintianing the same public API as a real camera that doesn't need this access.
+        """
         self._server = server
         return super().attach_to_server(server, path, setting_storage_path)
 
     def get_stage_position(self):
+        """Return the stage position.
+
+        The simulation camera has access to the stage position so it can generate a
+        different image as the stage moves.
+        """
         if not self._stage and self._server:
             self._stage = self._server.things["/stage/"]
         return self._stage.instantaneous_position

src/openflexure_microscope_server/things/settings_manager.py

@@ -128,6 +128,7 @@ class SettingsManager(lt.Thing):
 
     @property
     def thing_state(self) -> Mapping:
+        """Summary metadata describing the current state of the Thing."""
         state = {
             "hostname": self.hostname,
             "microscope-uuid": str(self.microscope_id),