Update documentation for new ReFrame classes

reframe_tests/tests/regression_checks.py

@@ -9,20 +9,37 @@ from reframe.utility import osext
 
 
 class RegressionCheck:
-    """Compare two .h5 files using h5diff"""
+    """Compare two hdf5 files using h5diff"""
 
     def __init__(
         self, output_file: Union[str, PathLike], reference_file: Union[str, PathLike]
     ) -> None:
+        """Create a new regression check.
+
+        Args:
+            output_file: Path to output file generate by the test.
+            reference_file: Path to reference file to run the regression
+                check against.
+        """
         self.output_file = Path(output_file)
         self.reference_file = Path(reference_file)
         self.h5diff_options: list[str] = []
 
     @property
     def error_msg(self) -> str:
+        """Message to display if the regression check fails"""
         return "Failed regression check"
 
     def create_reference_file(self) -> bool:
+        """Create reference file if it does not already exist.
+
+        The reference file is created as a copy of the current output
+        file.
+
+        Returns:
+            file_created: Returns True if a new file was created, False
+                if the path already exists.
+        """
         if not sn.path_exists(self.reference_file):
             self.reference_file.parent.mkdir(parents=True, exist_ok=True)
             copyfile(self.output_file, self.reference_file)
@@ -31,9 +48,26 @@ class RegressionCheck:
             return False
 
     def reference_file_exists(self) -> bool:
+        """Check if the reference file exists.
+
+        Returns:
+            file_exists: Returns true if the reference filepath is a
+                regular file, False otherwise.
+        """
         return sn.path_isfile(self.reference_file)
 
     def run(self) -> Literal[True]:
+        """Run the regression check using h5diff.
+
+        Returns:
+            check_passed: Returns True if the output file matches the
+                reference file (i.e. no output from h5diff). Otherwise,
+                raises a SanityError.
+
+        Raises:
+            reframe.core.exceptions.SanityError: If the output file does
+                not exist, or the regression check fails.
+        """
         if runtime().system.name == "archer2":
             h5diff = "/opt/cray/pe/hdf5/default/bin/h5diff"
         else:
@@ -50,7 +84,6 @@ class RegressionCheck:
             h5diff_output.stdout,
             (
                 f"{self.error_msg}\n"
-                # f"For more details run: 'h5diff {' '.join(self.h5diff_options)} {self.output_file} {self.reference_file}'\n"
                 f"For more details run: '{' '.join(h5diff_output.args)}'\n"
                 f"To re-create regression file, delete '{self.reference_file}' and rerun the test."
             ),
@@ -58,6 +91,12 @@ class RegressionCheck:
 
 
 class ReceiverRegressionCheck(RegressionCheck):
+    """Run regression check on individual reveivers in output files.
+
+    This can include arbitrary receivers in each file, or two receivers
+    in the same file.
+    """
+
     def __init__(
         self,
         output_file: Union[str, PathLike],
@@ -65,6 +104,17 @@ class ReceiverRegressionCheck(RegressionCheck):
         output_receiver: Optional[str],
         reference_receiver: Optional[str] = None,
     ) -> None:
+        """Create a new receiver regression check.
+
+        Args:
+            output_file: Path to output file generate by the test.
+            reference_file: Path to reference file to run the regression
+                check against.
+            output_receiver: Output receiver to check.
+            reference_receiver: Optional receiver to check against in
+                the reference file. If None, this will be the same as
+                the output receiver.
+        """
         super().__init__(output_file, reference_file)
 
         self.output_receiver = output_receiver
@@ -80,6 +130,8 @@ class ReceiverRegressionCheck(RegressionCheck):
 
 
 class SnapshotRegressionCheck(RegressionCheck):
+    """Run regression check on a gprMax Snapshot."""
+
     @property
     def error_msg(self) -> str:
         return f"Snapshot '{self.output_file.name}' failed regression check "