More changes suggested in review, generally docstring issues.

src/openflexure_microscope_server/scan_directories.py

@@ -73,8 +73,8 @@ class ScanDirectoryManager:
     ) -> Optional[str]:
         """Return the file path for the file within a scan directory
 
-        If check_exists is True then a FileNotFoundError will be raised if
-        the file does not exist.
+        If check_exists is True then None will be returned if the file does
+        not exist.
         """
         file_path = os.path.join(self.path_for(scan_name), filename)
         if check_exists:
@@ -178,13 +178,10 @@ class ScanDirectoryManager:
         """
         Raise an exception if there is not enough free disk space to continue scanning
 
-        Args:
-        path =  path to a location on the disk you want to check
-        min_space [int] = the minimum space required in bytes
-            default = 500,000,000 (500MB)
+        :param min_space: the minimum space required in bytes.
+            Default = 500,000,000 (500MB)
 
-        Raises:
-            NotEnoughFreeSpaceError if the remaining storage is below min_space
+        :raises: NotEnoughFreeSpaceError if the remaining storage is below min_space
         """
         disk_usage = shutil.disk_usage(self._base_scan_dir)
         if disk_usage.free < min_space:
@@ -198,7 +195,8 @@ class ScanDirectory:
     """A class for handling interactions with scan directories
 
     Initalisation parameters:
-      dir_path: the directory of the outer scan directory
+      name: the name of the scan (the scan directory basename)
+      base_scan_dir: Path of the directory that holds all scans
     """
 
     _name: str

src/openflexure_microscope_server/things/smart_scan.py

@@ -49,7 +49,7 @@ STITCHING_RESOLUTION = (820, 616)
 
 
 class ScanNotRunningError(RuntimeError):
-    """Method called when scan not running that requires a scan to be running"""
+    """Exception called when scan not running that requires a scan to be running"""
 
 
 def _scan_running(method):
@@ -138,8 +138,8 @@ class SmartScanThing(Thing):
         self._capture_thread = None
         self._scan_images_taken = 0
 
-        # Set _scan_data to None. It will for error checking. It will be set to a value
-        # by _run_scan
+        # Set _scan_data to None. This is needed just in case an exception is raised
+        # before _run_scan (which sets the real data). As we check this in the `except`
         self._scan_data = None
 
         try:

tests/mock_things/mock_background_detect.py

@@ -11,8 +11,6 @@ from openflexure_microscope_server.things.background_detect import ChannelDistri
 
 
 class MockBackgoundDetectThing:
-    # Counter for checking functions were called
-
     background_distributions = ChannelDistributions(
         means=[128.0, 128.0, 128.0],
         standard_deviations=[3.0, 3.0, 3.0],

tests/test_scan_directories.py

@@ -281,7 +281,13 @@ def test_creating_scan_dir_for_missing_scan():
 
 
 def test_none_returned_for_missing_images_dir():
-    """None should be returned for image dir path if images dir never created."""
+    """None should be returned for image dir path if images dir does not exist.
+
+    By default images directories are created at the same time the scan directory
+    is created. However, edge cases such as problems in deletions, microscopes
+    with older scans on, etc can cause and empty scan directory, so it is handled
+    explicitly.
+    """
     _clear_scan_dir()
     os.makedirs(os.path.join(BASE_SCAN_DIR, "fake_scan_0001"))
     scan_dir = ScanDirectory(BASE_SCAN_DIR, "fake_scan_0001")

tests/test_smart_scan.py

@@ -54,6 +54,11 @@ def smart_scan_thing():
 
 
 def test_initial_properties(smart_scan_thing):
+    """Check the initial values of properties.
+
+    Test properties of SmartScanThing are available without a ThingServer
+    and return expected default values.
+    """
     assert smart_scan_thing._scan_dir_manager.base_dir == SCAN_DIR
     assert smart_scan_thing.latest_scan_name is None
 
@@ -125,6 +130,7 @@ def test_public_delete_scan(smart_scan_thing, caplog):
 
 
 def test_delete_all_scans(smart_scan_thing, caplog):
+    """Check the delete_all_scan API really does delete all the scans."""
     _clear_scan_dir()
     with caplog.at_level(logging.INFO):
         fake_scan_names = [