Single line summaries of docstrings

tests/test_scan_directories.py

@@ -183,9 +183,7 @@ def test_scan_sequence_and_listing():
 
 
 def test_scan_name_non_sequential():
-    """Check created scans is the correct name if the directories
-    are not sequential
-    """
+    """Check new scan has the correct name if the directories are not sequential"""
     _clear_scan_dir()
     os.makedirs(os.path.join(BASE_SCAN_DIR, "fake_scan_0001"))
     os.makedirs(os.path.join(BASE_SCAN_DIR, "fake_scan_0002"))

tests/test_scan_planners.py

@@ -222,8 +222,10 @@ def test_mark_wrong_location():
 
 
 def test_closest_focus_wth_large_numbers():
-    """The number of steps gets very large in reality runs some tests to check
-    that everything works well with huge numbers of steps
+    """Tests to check that everything works well with huge numbers of steps.
+
+    The number of steps gets very large on the micorscope. But most of the tests
+    above use smaller numbers for clarity.
     """
     intial_position = (0, 0)
     # Set this up, but we won't use the settings
@@ -247,11 +249,18 @@ def test_closest_focus_wth_large_numbers():
 
 
 def test_example_smart_spiral():
-    """Test the smart spiral scan algorithm on the sample types listed
-    below and defined in scan_test_helpers.load_sample_points
+    """Test the smart spiral scan algorithm on the different sample types.
 
-    Will fail if the locations or path between locations visited has changed
-    for any of the samples listed
+    The sample types:
+
+    * ``regular``
+    * ``lobed``
+    * ``core"``
+
+    These are defined in scan_test_helpers.load_sample_points
+
+    This will fail if the locations or path between locations visited has changed
+    for any of the samples listed.
     """
     example_samples = [
         "regular",

tests/test_smart_scan.py

@@ -63,8 +63,10 @@ def test_initial_properties(smart_scan_thing):
 
 
 def test_inaccessible_scan_methods(smart_scan_thing):
-    """The @_scan_running decorator should make some methods
-    inaccessible unless a scan is running
+    """Test that method with @_scan_running decorator is inaccessible.
+
+    The @_scan_running decorator makes these functions inacessible unless
+    a scan is running.
     """
     with pytest.raises(ScanNotRunningError):
         smart_scan_thing._run_scan()

tests/test_stack.py

@@ -46,7 +46,7 @@ def even_integers(min_value=0, max_value=1000):
     extra_ims=even_integers(min_value=0, max_value=10),
 )
 def test_stack_params_validation(save_ims, extra_ims):
-    """Tests specifically the validation on the image numbers
+    """Test the validation of the image numbers for a stack.
 
     save_ims is the number to save (must be odd and positive)
     extra_ims is how many more images there are in min_images_to_test than
@@ -68,8 +68,9 @@ def test_stack_params_validation(save_ims, extra_ims):
     extra_ims=even_integers(min_value=-10, max_value=-1),
 )
 def test_stack_params_not_enough_test_images(save_ims, extra_ims):
-    """Set the extra_ims negative so that min_images_to_test is smaller
-    than images_to_save.
+    """Test error is raised if min_images_to_test is smaller than images_to_save.
+
+    ``extra_ims`` negative so that min_images_to_test is smaller than images_to_save.
 
     For arguments see test_stack_params_validation
     """

tests/utilities/scan_test_helpers.py

@@ -14,23 +14,23 @@ THIS_DIR = os.path.dirname(os.path.realpath(__file__))
 
 
 class FakeSample:
-    """A fake sample to test scan algorithms. The sample is able to return
-    whether a given position is sample, no image associated with the sample
+    """A fake sample to test scan algorithms.
+
+    The sample is able to return whether a given position is sample, there is no image
+    associated with the sample
     """
 
     def __init__(self, xy_points: list[tuple[int, int]]):
-        """Create the sample from a spline interpolation around
-        the given points.
-        """
+        """Create the sample from a spline interpolation around the given points."""
         self._sample_perimeter = interp_closed_path(xy_points, 500)
 
     def is_sample(self, pos: tuple[int, int], im_size: tuple[int, int]) -> bool:
-        """Return whether an image at a given location with a given image size
-        is on the sample
+        """Return True if an image at a given location is on the sample.
 
-        This doesn't check the entire image field as this is designed to be used
-        where the fake sample is much larger than the image and has smooth edges
-        It just checks the 4 corners
+        The image size is specified to check if it overlaps the sample. It doesn't
+        check the entire image field as this is designed to be used where the fake
+        sample is much larger than the image and has smooth edges. It just checks the
+        4 corners.
         """
         img_corners = [
             (pos[0] + im_size[0], pos[1] + im_size[1]),
@@ -77,8 +77,9 @@ def visualise_scan(sample: FakeSample, planner: scan_planners.ScanPlanner) -> Fi
 
 
 def interp_closed_path(xy_points: list[tuple[int, int]], n_points: int) -> MatPath:
-    """Given a lists of xy_points interpolate an n_point closed curve. This can be used
-    to create an arbitrary sample shape plan a scan.
+    """Interpolate an n_point closed curve from a lists of xy_points.
+
+    This can be used to create an arbitrary sample shape for testing a scan planner.
 
     Modified from:
     https://stackoverflow.com/questions/33962717/interpolating-a-closed-curve-using-scipy
@@ -105,8 +106,9 @@ def interp_closed_path(xy_points: list[tuple[int, int]], n_points: int) -> MatPa
 def example_smart_spiral(
     sample_name: str = "lobed",
 ) -> tuple[FakeSample, scan_planners.ScanPlanner]:
-    """Run an example scan and return the sample scanned and the planner object
-    after scan is complete
+    """Run an example scan.
+
+    :returns: The sample scanned and the planner object after scan is complete.
     """
     xy_sample_points = load_sample_points(sample_name)
     sample = FakeSample(xy_sample_points)
@@ -126,11 +128,11 @@ def example_smart_spiral(
 
 
 def profile_and_save_plot_for_example_smart_spiral():
-    """Run the example scan and save a plot and the profile data
-    Also print the cumulative stats
+    """Run the example scan and save a plot and the profile data.
 
+    Also print the cumulative stats.
 
-    This runs if you run this file directly
+    This runs if you run this file directly.
     """
     import pstats
     import cProfile
@@ -152,8 +154,9 @@ def profile_and_save_plot_for_example_smart_spiral():
 
 
 def update_example_smart_spiral_pickle(sample_name: str):
-    """Pickle the ScanPlanner for the example_smart_spiral(),
-    this is done so the history can be compared by testing to check
+    """Pickle the ScanPlanner for the example_smart_spiral().
+
+    This is done so the history can be compared by testing to check
     the algorithm is unchanged.
 
     If the algorithm is purposefully changed then this will need to be
@@ -171,8 +174,9 @@ def update_example_smart_spiral_pickle(sample_name: str):
 def get_expected_result_for_example_smart_spiral(
     sample_name: str,
 ) -> scan_planners.ScanPlanner:
-    """Return the expected ScanPlanner object for the example_smart_spiral(),
-    this is pickled, so that it can be committed.
+    """Return the expected ScanPlanner object for the example_smart_spiral().
+
+    This is loaded from a pickle so that the object can be committed to the repo.
     """
     pkl_fname = os.path.join(THIS_DIR, f"example_smart_spiral_{sample_name}.pkl")
     with open(pkl_fname, "rb") as pkl_file_obj: