added doc string for save_table_with_header

1 files changed, 26 insertions, 5 deletions

diff --git a/qolab/file_utils/__init__.py b/qolab/file_utils/__init__.py
index 849718d..e61811e 100644
--- a/qolab/file_utils/__init__.py
+++ b/qolab/file_utils/__init__.py
@@ -70,11 +70,32 @@ def get_next_data_file(prefix, savepath, run_number=None, datestr=None, date_for
     return(fname)
 
 def save_table_with_header(fname, data, header='', comment_symbol='%', skip_headers_if_file_exist=False, item_format='e', item_separator='\t', compressionmethod=None, compresslevel=9):
-    # itemFormat examples: 'e', '.15e', 'f'
-    # `compressionmethod` can be
-    #   None - no compression
-    #   "gzip" - gzip method of compression
-    # `compresslevel`: 9 the highest compression, 0 no compression at all, as it is defined for gzip in Lib/gzip.py
+    """Saves output to CSV or TSV file with specially formatted header.
+
+    The file is appended if needed.
+    It is possible to compress output file.
+
+    Parameters
+    ----------
+    fname : string, full path of the saved file.
+    data : array type (python or numpy).
+    header : list or array of header strings to put at the beginning of the record
+    comment_symbol : prefix for the header lines, default is '%'.
+        Note that headers are actually prefixed with <comment_symbol> and <space>.
+        Historically it is chosen as '%' to make files compatible with Matlab `load`.
+        '#' symbmol is also good choice.
+    skip_headers_if_file_exist : True or False (default).
+        When True skip addition of headers in already existing file.
+        Useful when appending to file with the same headers.
+    item_format : output format like in formatted strings, examples are 'e', '.15e', 'f'
+    item_separator : how to separate columns, '\t' is default.
+        Natural choices are either ',' (comma) or '\t' (tab).
+    compressionmethod :  compression method
+        - None : no compression (default)
+        - gzip : gzip method of compression
+        - bzip : bzip2 method of compression
+    compresslevel : 9 (default) the highest compression, 0 no compression at all, as it is defined for gzip in Lib/gzip.py
+    """
     fname = filename2os_fname(fname)
     file_exist_flag = os.path.exists(fname)
     item_format=str.join('', ['{', f':{item_format}', '}'])