From 2d4838cac379711dc6ffc10781326a555cbde447 Mon Sep 17 00:00:00 2001
From: Josh Humphries <j.humphries@nhm.ac.uk>
Date: Wed, 8 Nov 2023 22:20:58 +0000
Subject: [PATCH] test: add comments to the dumps helper module's functions

---
 tests/helpers/samples/dumps.py | 49 ++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/tests/helpers/samples/dumps.py b/tests/helpers/samples/dumps.py
index 36b28ea..4687f22 100644
--- a/tests/helpers/samples/dumps.py
+++ b/tests/helpers/samples/dumps.py
@@ -4,6 +4,12 @@
 
 
 class EcatalogueType(Enum):
+    """
+    An ecatalogue record type, the value assigned to each enum option is the
+    ColRecordType value each is filtered on (well, for specimen, it's an example one as
+    there are many.
+    """
+
     specimen = "Specimen"
     indexlot = "Index Lot"
     artefact = "Artefact"
@@ -13,6 +19,17 @@ class EcatalogueType(Enum):
 def create_ecatalogue(
     irn: str, ecatalogue_type: EcatalogueType, guid: Optional[str] = None, **extras
 ) -> dict:
+    """
+    Make a sample ecatalogue record of the given type with the given irn, optional guid
+    and extra key/value pairs. Returns a dict which should pass the given type's view's
+    is_member function.
+
+    :param irn: the ID of the record
+    :param ecatalogue_type: the EcatalogueType of the record to return
+    :param guid: a guid for the record, can be None in which case one is generated
+    :param extras: any extra key/value pairs to include in the dict
+    :return: a dict
+    """
     base = {
         "irn": irn,
         "ColRecordType": ecatalogue_type.value,
@@ -27,6 +44,16 @@ def create_ecatalogue(
 
 
 def create_emultimedia(irn: str, guid: Optional[str] = None, **extras):
+    """
+    Make a sample emultimedia record with the given irn, optional guid and extra
+    key/value pairs. Returns a dict which should pass the image view's is_member
+    function.
+
+    :param irn: the ID of the record
+    :param guid: a guid for the record, can be None in which case one is generated
+    :param extras: any extra key/value pairs to include in the dict
+    :return: a dict
+    """
     return {
         "irn": irn,
         "MulMimeType": "image",
@@ -39,6 +66,14 @@ def create_emultimedia(irn: str, guid: Optional[str] = None, **extras):
 
 
 def create_etaxonomy(irn: str, **extras):
+    """
+    Make a sample etaxonomy record with the given irn, optional guid and extra key/value
+    pairs. Returns a dict which should pass the taxonomy view's is_member function.
+
+    :param irn: the ID of the record
+    :param extras: any extra key/value pairs to include in the dict
+    :return: a dict
+    """
     return {
         "irn": irn,
         "AdmPublishWebNoPasswordFlag": "Y",
@@ -47,6 +82,13 @@ def create_etaxonomy(irn: str, **extras):
 
 
 def create_eaudit(irn_to_delete: str, table_to_delete_from: str) -> dict:
+    """
+    Make a sample eaudit record which deletes the given irn from the given table.
+
+    :param irn_to_delete: the ID of the record to delete
+    :param table_to_delete_from: the table to delete the record from
+    :return: a dict
+    """
     return {
         # doesn't matter what the irn of this record is so just always set it to -1
         "irn": "-1",
@@ -57,6 +99,13 @@ def create_eaudit(irn_to_delete: str, table_to_delete_from: str) -> dict:
 
 
 def read_emu_extract(text: str) -> Tuple[str, dict]:
+    """
+    Reads the given text and turns it into a record ID and a dict of the record's data.
+    The text is expected to be in the EMu dump format.
+
+    :param text: some raw text
+    :return: the ID and the data as a 2-tuple
+    """
     data = {}
     for line in text.split("\n"):
         line = line.strip()