tableflow: from comments to docstrings

1 files changed, 21 insertions, 11 deletions

diff --git a/qolab/tableflow/__init__.py b/qolab/tableflow/__init__.py
index 1466dde..2bd4378 100644
--- a/qolab/tableflow/__init__.py
+++ b/qolab/tableflow/__init__.py
@@ -16,6 +16,7 @@ import pandas as pd
 import warnings
 
 def loadInOutTables(inputFileName=None, outputFileName=None, comment=None):
+    """Load input table from a file and if exist output table too, otherwise clone input table to the output one."""
     if not inputFileName:
         return None, None
 
@@ -33,8 +34,11 @@ def loadInOutTables(inputFileName=None, outputFileName=None, comment=None):
     return tIn, tOut
 
 def ilocRowOrAdd(tbl, row):
-    # Find similar 'row' in 'tbl', NA in both set treated as a hit.
-    # if similar row not found, insert it.
+    """Find a row in a table ('tbl') similar to a provided 'row' in 'tbl'.
+
+    NA in both sets treated as a match.
+    If similar 'row' not found in the table, insert it. 
+    """
     tSub = tbl[row.keys()]
     res = (tSub == row) | (tSub.isna() & row.isna() )
     res = res.all(axis=1) # which rows coincide
@@ -48,13 +52,17 @@ def ilocRowOrAdd(tbl, row):
     return i
 
 def updateTblRowAt(tbl, i, row):
+    """Update row  with position 'i' in the table ('tbl') with values from 'row'."""
     for k in row.keys():
         tbl.at[i, k] = row[k]
     return
 
 def isRedoNeeded(row, cols2check):
-    # redo is required if *all* required entries in cols2check are NA
-    # or we are missing columns in cols2check list
+    """Check is Redo required in a given row.
+
+    Redo is required if *all* required entries in 'cols2check' are NA
+    or we are missing columns in cols2check list
+    """
     for c in cols2check:
         if c not in row.keys():
             return True
@@ -63,13 +71,15 @@ def isRedoNeeded(row, cols2check):
     return False
 
 def reflowTable(tIn, tOut, process_row_func=None, postProcessedColums=None, extraInfo=None, redo=False):
-    # update tOut in place based on the inputs specified in tIn
-    # effectively maps unprocess rows in to process_row_func
-    # - postProcessedColums is a list of column names which need to be generated
-    # - extraInfo is dictionary of additional parameter supplied to process_row_func
-    # - process_row_func expected to behave like:
-    #   rowOut = process_row_func(rowIn, extraInfo=userInfo)
-    # - redo controls if reflow is needed unconditionally (i.e. force reflow)
+    """Reflow/update tOut in place based on the inputs specified in tIn.
+
+    Effectively maps unprocess rows to 'process_row_func'
+    - postProcessedColums is a list of column names which need to be generated
+    - extraInfo is dictionary of additional parameter supplied to process_row_func
+    - process_row_func expected to behave like:
+      rowOut = process_row_func(rowIn, extraInfo=userInfo)
+    - redo controls if reflow is needed unconditionally (i.e. force reflow)
+    """
     if not process_row_func:
         warnings.warn("process_row_func is not provided, exiting reflowTable")
         return