No starting docstrings with This

integration-tests/testfile.py

@@ -1,11 +1,10 @@
 #! /usr/bin/env python3
-"""This module fires up a server in a subprocess to allow for integration tests.
+"""Start a server subprocess for integration tests.
 
-These are separated from the unit tests to stop them artificially inflating the test
+These tests are separated from unit tests to avoid inflating test coverage.
-coverage. For now this file should be run directly not with a test framework.
+For now, this file should be run directly rather than through a test framework.
 
-These tests are designed to run on CI. They should work on Linux or WSL for local
+They are designed to run on CI and should work on Linux or WSL for local debugging.
-debugging.
 """
 
 from typing import Optional

pyproject.toml

@@ -133,7 +133,6 @@ ignore = [
     "D415",
     "D400",
     "D200",
-    "D404",
     # These should be turned on before this MR is complete
     "D100",
     "D102",

src/openflexure_microscope_server/scan_directories.py

@@ -1,9 +1,4 @@
-"""
+"""Functionality to manage file system operations for scan directories."""
-This submodule contains functionality for interacting with scan directories.
-
-Currently it handles scan getting information from a information from a scan directory,
-eventually is should handle all the file system operation for smart_scan.
-"""
 
 from typing import Optional
 import os

src/openflexure_microscope_server/scan_planners.py

@@ -1,5 +1,4 @@
-"""
+"""Functionality for planning scan routes.
-This module contains functionality for planning a scan route
 
 A scan route can be planned by a ScanPlanner class currently there
 is only one type the SmartSpiral. More can be added using by
@@ -242,14 +241,14 @@ class ScanPlanner:
 
 
 class SmartSpiral(ScanPlanner):
-    """
+    """A scan planner that spirals outward from the centre, prioritising short moves.
-    This is a smart spiral scan that spirals out from the centre, but prioritises
+
-    short moves over rigidly sticking to minimising radius from the centre of the
+    This planner spirals out from the centre, but prioritises short moves over rigidly
-    scan.
+    sticking to minimising radius from the centre of the scan.
 
     Each time and image is taken the four neighbouring images are added
-    to the list of poisitions to image (unless they are already listed or
+    to the list of positions to image (unless they are already listed or
-    tried). However if a location is not imaged due no sample being detected
+    tried). However, if a location is not imaged due no sample being detected
     then neibouring positions are not imaged.
 
     The next image taken is the closes to the centre (considering the largest

src/openflexure_microscope_server/things/camera/picamera.py

@@ -1,5 +1,4 @@
-"""
+"""Submodule for interacting with a Raspberry Pi camera using the Picamera2 library.
-This SubModule interacts with a Raspberry Pi camera using the Picamera2 library.
 
 The Picamera2 library uses LibCamera as the underlying camera stack. This gives us
 some control of the GPU pipeline for the image.

src/openflexure_microscope_server/utilities.py

@@ -1,14 +1,12 @@
-"""
+"""Utility functions and classes."""
-This module contains some utility functions and classes
-"""
 
 from threading import Thread
 
 
 class ErrorCapturingThread(Thread):
-    """
+    """Subclass of Thread that captures exceptions from the target function.
-    This is a a subclass or Thread. It wraps the target function in a
+
-    try-except block.
+    It wraps the target function in a try-except block.
 
     Execution will stop with an unhandled exception, but the exception will not be raised
     until the join method is called. When the join method is called, the exception is

tests/mock_things/mock_autofocus.py

@@ -1,10 +1,10 @@
-"""This testing submodule contains mock autofocus things.
+"""Testing submodule with mock Autofocus Things.
 
-These mocks are designed to be inserted as dependencies to give specific
+These mocks are designed to be inserted as dependencies to provide specific
-functionality and returns.
+functionality and return values.
 
-The mocks do not subclass, and instead return very specific defined answers
+The mocks do not subclass Things. Instead, they return predefined
-to functions
+answers to functions.
 """
 
 

tests/mock_things/mock_background_detect.py

@@ -1,10 +1,10 @@
-"""This testing submodule contains mock background detect things.
+"""Testing submodule with mock Background Detect Things.
 
-These mocks are designed to be inserted as dependencies to give specific
+These mocks are designed to be inserted as dependencies to provide specific
-functionality and returns.
+functionality and return values.
 
-The mocks do not subclass, and instead return very specific defined answers
+The mocks do not subclass Things. Instead, they return predefined
-to functions
+answers to functions.
 """
 
 from openflexure_microscope_server.things.background_detect import ChannelDistributions

tests/mock_things/mock_csm.py

@@ -1,10 +1,10 @@
-"""This testing submodule contains mock camera stage mapping things.
+"""Testing submodule with mock Camera Stage Mapping Things.
 
-These mocks are designed to be inserted as dependencies to give specific
+These mocks are designed to be inserted as dependencies to provide specific
-functionality and returns.
+functionality and return values.
 
-The mocks do not subclass, and instead return very specific defined answers
+The mocks do not subclass Things. Instead, they return predefined
-to functions
+answers to functions.
 """
 
 

tests/mock_things/mock_stage.py

@@ -1,10 +1,10 @@
-"""This testing submodule contains stage things.
+"""Testing submodule with mocks StageThings.
 
-These mocks are designed to be inserted as dependencies to give specific
+These mocks are designed to be inserted as dependencies to provide specific
-functionality and returns.
+functionality and return values.
 
-The mocks do not subclass, and instead return very specific defined answers
+The mocks do not subclass existing Things. Instead, they return predefined
-to functions
+answers to functions.
 """
 
 

tests/test_scan_planners.py

@@ -96,11 +96,11 @@ def test_bad_smart_spiral_settings():
 
 
 def test_smart_spiral_first_few_pos():
-    """
+    """Test for correct data addition during initial scan positions.
-    This test is  VERY long, not really a "unit". It checks step-by-step
-    that data is added correctly for the first few postions in a scan.
 
-    This should catch basic cases of if the algorithm is updated.
+    This is a very long test, not strictly a "unit" test. It checks step by step
+    that data is added correctly for the first few positions in a scan. It is
+    intended to catch basic issues if the algorithm is updated.
     """
     intial_position = (100, 50)
     planner_settings = {"dx": 50, "dy": 50, "max_dist": 10000}
@@ -206,12 +206,7 @@ def test_smart_spiral_stops_on_max_dist():
 
 
 def test_mark_wrong_location():
-    """
+    """Check that an error is raised if a scan marks the wrong location as visited."""
-    This test is  VERY long, not really a "unit". It checks step-by-step
-    that data is added correctly for the first few postions in a scan.
-
-    This should catch basic caseses of if the algorithm is updated.
-    """
     intial_position = (100, 50)
     planner_settings = {"dx": 50, "dy": 50, "max_dist": 10000}
     # Create a planner

tests/test_smart_scan.py

@@ -175,17 +175,11 @@ def _run_only_outer_scan(adjust_inital_state: Optional[Callable] = None):
     bkgrnd_det_mock = MockBackgoundDetectThing()
 
     class MockedSmartScanThing(SmartScanThing):
-        """
+        """Mocked version of SmartScanThing with a patched _run_scan method."""
-        This is a subclass of SmartScanThing with a mocked method and
-        mocked thing_settings.
-        """
 
         # Counter for checking functions were called
         mock_call_count = {"_run_scan": 0}
 
-        # Mock thing settings as a dictionary
-        thing_settings = {"skip_background": True}
-
         def _run_scan(self):
             self.mock_call_count["_run_scan"] += 1
 

tests/utilities/__init__.py

@@ -1,8 +1,8 @@
 """
-This sub-package contains utilities that help with testing and debugging.
+Utilities for testing and debugging.
 
-At the top level are some very basic testing functions, more specific testing
+At the top level are some basic testing functions. More specific testing utilities are
-is provided by modules inside the package.
+provided by modules inside the package.
 """
 
 from typing import Protocol, Iterable