update docstrings for tests

tests/generation_of_input_data_subset.md

@@ -1,13 +1,13 @@
-# Generation of Input Data that is Subset
+# Generation of Input Data Workflow/Processing Tests
 
-We do a lot of validation of the input data including ensuring all the burst data provided as input is coregistered, that their dates are consistent, etc.
-However, there is a nice way to "trick" our workflows into processing a smaller set of inputs - we can replace the input RTC-S1 with a cropped subset.
+The DIST-S1 runconfig does a lot of validation of the input data including ensuring all the burst data provided as input is coregistered, that their dates are consistent, etc.
+However, there is a nice way to "trick" (or "flaw") in our workflows that can be exploited into processing a smaller set of data - we can replace the input RTC-S1 with a cropped subset georeferenced to the cropped area.
 Despite all the validation we do, we do not check that the input burst data itself spans some fixed area (so if we replace the expected input file with a cropped subset, the workflow will not catch this and still run).
 So we can provide inputs that are a small fraction of what is nominally provided and ensure the workflow runs correctly.
 
 We do a considerable amount of testing and since our workflow is IO heavy, we have to be careful in regards to providing paths to the workflow.
 
-This generation is shown here: https://github.com/OPERA-Cal-Val/dist-s1-research/blob/dev/marshak/S_create_test_data/Generate_Test_Data.ipynb 
+This data generation of how we can crop this data is shown here: https://github.com/OPERA-Cal-Val/dist-s1-research/blob/dev/marshak/S_create_test_data/Generate_Test_Data.ipynb 
 The data is then transferred to `test_data/cropped`.
 
 If you want to update this dataset, it requires some care.
@@ -23,3 +23,9 @@ Lastly, it is important to utilize
 
 - `test_runconfig_model.py` - ensures the runcofig data is instantiated correctly from the metadata - needs correct file paths
 - `test_workflows.py` - ensures the workflow runs and the outputs are correct - needs correct file paths, a golden dataset (see `conftest.py` for the path of the location provided). Also workflow steps are tested and so intermediate tests are generated.
+
+# Water Mask Tests
+
+The water mask tests are in `tests/test_water_mask.py`. We test the function `water_mask_control_flow` which is in the file `src/dist_s1/water_mask.py`.
+The tests are hopefully self-explanatory.
+Generating the sample water masks are found here: https://github.com/OPERA-Cal-Val/dist-s1-research/blob/dev/marshak/S_create_test_data/Water_Mask_Generation.ipynb

tests/test_water_mask.py

@@ -9,6 +9,7 @@
 
 
 def test_good_water_mask_path(test_dir: Path, good_water_mask_path_for_17SLR: Path) -> None:
+    """Apply the water mask control flow to a water mask that is buffered by .25 degrees around the MGRS tile."""
     tmp_dir = test_dir / 'tmp'
     tmp_dir.mkdir(parents=True, exist_ok=True)
 
@@ -39,6 +40,7 @@ def test_good_water_mask_path(test_dir: Path, good_water_mask_path_for_17SLR: Pa
 
 
 def test_bad_water_mask_path(test_dir: Path, bad_water_mask_path_for_17SLR: Path) -> None:
+    """Apply the water mask control flow to a water mask that is eroded by -.25 degrees around the MGRS tile."""
     tmp_dir = test_dir / 'tmp'
 
     with pytest.raises(ValueError):
@@ -51,6 +53,7 @@ def test_bad_water_mask_path(test_dir: Path, bad_water_mask_path_for_17SLR: Path
 
 
 def test_bad_file_path(test_dir: Path) -> None:
+    """Apply the water mask control flow to a file that does not exist."""
     tmp_dir = test_dir / 'tmp'
 
     with pytest.raises(FileNotFoundError):
@@ -63,6 +66,7 @@ def test_bad_file_path(test_dir: Path) -> None:
 
 
 def test_antimeridian_water_mask(test_dir: Path, antimeridian_water_mask_path_for_01VCK: Path) -> None:
+    """Apply the water mask control flow to a water mask file that crosses the antimeridian."""
     tmp_dir = test_dir / 'tmp'
     tmp_dir.mkdir(parents=True, exist_ok=True)