From 3edc6f67bb50552d0ce0e3ec372b06efb736cdb8 Mon Sep 17 00:00:00 2001
From: Frederick Muriuki Muriithi
Date: Wed, 3 Jan 2024 09:15:29 +0300
Subject: Rename argument and add documentation to functions.

---
 r_qtl/r_qtl2.py | 27 +++++++++++++++++++++------
 1 file changed, 21 insertions(+), 6 deletions(-)

diff --git a/r_qtl/r_qtl2.py b/r_qtl/r_qtl2.py
index 79a0656..bc3a86f 100644
--- a/r_qtl/r_qtl2.py
+++ b/r_qtl/r_qtl2.py
@@ -35,8 +35,16 @@ def control_data(zfile: ZipFile) -> dict:
 def with_non_transposed(zfile: ZipFile,
                         member_key: str,
                         cdata: dict,
-                        func: Callable[[dict], dict] = lambda val: val) -> Iterator[dict]:
-    """Abstracts away common file-opening for non-transposed R/qtl2 files."""
+                        process_value: Callable[
+                            [dict], dict] = lambda val: val) -> Iterator[dict]:
+    """Process non-transposed file values
+
+    Arguments:
+    zfile: A zipfile object from opening a R/qtl2 bundle.
+    member_key: A key to retrieve the member file to process from the file.
+    cdata: The control data from the R/qtl2 bundle read from the JSON/YAML file.
+    process_value: A function to process the values from the file.
+    """
     def not_comment_line(line):
         return not line.startswith(cdata.get("comment.char", "#"))
 
@@ -45,7 +53,7 @@ def with_non_transposed(zfile: ZipFile,
             filter(not_comment_line, io.TextIOWrapper(innerfile)),
             delimiter=cdata.get("sep", ","))
         for row in reader:
-            yield func(row)
+            yield process_value(row)
 
 def __make_organise_by_id__(id_key):
     """Return a function to use with `reduce` to organise values by some
@@ -66,10 +74,17 @@ def __batch_of_n__(iterable: Iterable, num):
 def with_transposed(zfile: ZipFile,
                     member_key: str,
                     cdata: dict,
-                    merge_function: Callable[
+                    process_value: Callable[
                         [str, tuple[str, ...], tuple[str, ...]],
                         tuple[dict, ...]]) -> Iterator[dict]:
-    """Abstracts away common file-opening for transposed R/qtl2 files."""
+    """Process transposed file values
+
+    Arguments:
+    zfile: A zipfile object from opening a R/qtl2 bundle.
+    member_key: A key to retrieve the member file to process from the file.
+    cdata: The control data from the R/qtl2 bundle read from the JSON/YAML file.
+    process_value: A function to process the values from the file.
+    """
     with zfile.open(cdata[member_key]) as innerfile:
         lines = (tuple(field.strip() for field in
                        line.strip().split(cdata.get("sep", ",")))
@@ -84,7 +99,7 @@ def with_transposed(zfile: ZipFile,
                     (row
                      for batch in __batch_of_n__(lines, 300)
                      for line in batch
-                     for row in merge_function(id_key, headers, line)),
+                     for row in process_value(id_key, headers, line)),
                     {}).items():
                 yield row
         except StopIteration:
-- 
cgit v1.2.3