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
-coverage. For now this file should be run directly not with a test framework.
+These tests are separated from unit tests to avoid inflating test coverage.
+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
-debugging.
+They are designed to run on CI and should work on Linux or WSL for local 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 @@
-"""
-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.
-"""
+"""Functionality to manage file system operations for scan directories."""
 
 from typing import Optional
 import os

src/openflexure_microscope_server/scan_planners.py

@@ -1,5 +1,4 @@
-"""
-This module contains functionality for planning a scan route
+"""Functionality for planning scan routes.
 
 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):
-    """
-    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
-    scan.
+    """A scan planner that spirals outward from the centre, prioritising short moves.
+
+    This planner spirals out from the centre, but prioritises short moves over rigidly
+    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
-    tried). However if a location is not imaged due no sample being detected
+    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
     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 @@
-"""
-This SubModule interacts with a Raspberry Pi camera using the Picamera2 library.
+"""Submodule for interacting 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 @@
-"""
-This module contains some utility functions and classes
-"""
+"""Utility functions and classes."""
 
 from threading import Thread
 
 
 class ErrorCapturingThread(Thread):
-    """
-    This is a a subclass or Thread. It wraps the target function in a
-    try-except block.
+    """Subclass of Thread that captures exceptions from the target function.
+
+    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
-functionality and returns.
+These mocks are designed to be inserted as dependencies to provide specific
+functionality and return values.
 
-The mocks do not subclass, and instead return very specific defined answers
-to functions
+The mocks do not subclass Things. Instead, they return predefined
+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
-functionality and returns.
+These mocks are designed to be inserted as dependencies to provide specific
+functionality and return values.
 
-The mocks do not subclass, and instead return very specific defined answers
-to functions
+The mocks do not subclass Things. Instead, they return predefined
+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
-functionality and returns.
+These mocks are designed to be inserted as dependencies to provide specific
+functionality and return values.
 
-The mocks do not subclass, and instead return very specific defined answers
-to functions
+The mocks do not subclass Things. Instead, they return predefined
+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
-functionality and returns.
+These mocks are designed to be inserted as dependencies to provide specific
+functionality and return values.
 
-The mocks do not subclass, and instead return very specific defined answers
-to functions
+The mocks do not subclass existing Things. Instead, they return predefined
+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():
-    """
-    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.
+    """Test for correct data addition during initial scan positions.
 
-    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():
-    """
-    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.
-    """
+    """Check that an error is raised if a scan marks the wrong location as visited."""
     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):
-        """
-        This is a subclass of SmartScanThing with a mocked method and
-        mocked thing_settings.
-        """
+        """Mocked version of SmartScanThing with a patched _run_scan method."""
 
         # 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
-is provided by modules inside the package.
+At the top level are some basic testing functions. More specific testing utilities are
+provided by modules inside the package.
 """
 
 from typing import Protocol, Iterable