finish a first pitch of docstrings

corrlib/toml.py

@@ -22,6 +22,18 @@ from typing import Any
 
 
 def replace_string(string: str, name: str, val: str) -> str:
+    """
+    Replace a placeholder {name} with a value in a string.
+
+    Parameters
+    ----------
+    string: str
+        String in which the placeholders are to be replaced.
+    name: str
+        The name of the placeholder.
+    val: str
+        The value the placeholder is to be replaced with.
+    """
     if '{' + name + '}' in string:
         n = string.replace('{' + name + '}', val)
         return n
@@ -30,7 +42,16 @@ def replace_string(string: str, name: str, val: str) -> str:
 
 
 def replace_in_meas(measurements: dict[str, dict[str, Any]], vars: dict[str, str]) -> dict[str, dict[str, Any]]:
-    # replace global variables
+    """
+    Replace placeholders in the defiitions for a measurement.
+
+    Parameters
+    ----------
+    measurements: dict[str, dict[str, Any]]
+        The measurements read from the toml file.
+    vars: dict[str, str]
+        Simple key:value dictionary with the keys to be replaced by the values.
+    """
     for name, value in vars.items():
         for m in measurements.keys():
             for key in measurements[m].keys():
@@ -43,6 +64,16 @@ def replace_in_meas(measurements: dict[str, dict[str, Any]], vars: dict[str, str
 
 
 def fill_cons(measurements: dict[str, dict[str, Any]], constants: dict[str, str]) -> dict[str, dict[str, Any]]:
+    """
+    Fill in defined constants into the measurements of the toml-file.
+
+    Parameters
+    ----------
+    measurements: dict[str, dict[str, Any]]
+        The measurements read from the toml file.
+    constants: dict[str, str]
+        Simple key:value dictionary with the keys to be replaced by the values.
+    """
     for m in measurements.keys():
         for name, val in constants.items():
             if name not in measurements[m].keys():
@@ -51,6 +82,14 @@ def fill_cons(measurements: dict[str, dict[str, Any]], constants: dict[str, str]
 
 
 def check_project_data(d: dict[str, dict[str, str]]) -> None:
+    """
+    Check the data given in the toml import file for the project we want to import.
+
+    Parameters
+    ----------
+    d: dict
+        The dictionary holding the data necessary to import the project.
+    """
     if 'project' not in d.keys() or 'measurements' not in d.keys() or len(list(d.keys())) > 4:
         raise ValueError('There should only be maximally be four keys on the top level, "project" and "measurements" are mandatory, "contants" is optional!')
     project_data = d['project']
@@ -64,6 +103,16 @@ def check_project_data(d: dict[str, dict[str, str]]) -> None:
 
 
 def check_measurement_data(measurements: dict[str, dict[str, str]], code: str) -> None:
+    """
+    Check syntax of the measurements we want to import.
+
+    Parameters
+    ----------
+    measurements: dict[str, dict[str, str]]
+        The dictionary holding the necessary data to import the project.
+    code: str
+        The code used for the project.
+    """
     var_names: list[str] = []
     if code == "sfcf":
         var_names = ["path", "ensemble", "param_file", "version", "prefix", "cfg_seperator", "names"]
@@ -78,8 +127,21 @@ def check_measurement_data(measurements: dict[str, dict[str, str]], code: str) -
 
 
 def import_tomls(path: str, files: list[str], copy_files: bool=True) -> None:
+    """
+    Import multiple toml files.
+
+    Parameters
+    ----------
+    path: str
+        Path to the backlog directory.
+    files: list[str]
+        Path to the description files.
+    copy_files: bool, optional
+        Whether the toml-files will be copied into the library. Default is True.
+    """
     for file in files:
         import_toml(path, file, copy_files)
+    return
 
 
 def import_toml(path: str, file: str, copy_file: bool=True) -> None:
@@ -92,6 +154,8 @@ def import_toml(path: str, file: str, copy_file: bool=True) -> None:
         Path to the backlog directory.
     file: str
         Path to the description file.
+    copy_file: bool, optional
+        Whether the toml-files will be copied into the library. Default is True.
     """
     print("Import project as decribed in " + file)
     with open(file, 'rb') as fp:
@@ -180,6 +244,16 @@ def reimport_project(path: str, uuid: str) -> None:
 
 
 def update_project(path: str, uuid: str) -> None:
+    """
+    Update all entries associated with a given project.
+
+    Parameters
+    ----------
+    path: str
+        The path of the library.
+    uuid: str
+        The unique identifier of the project to be updated.
+    """
     dl.update(how='merge', follow='sibling', dataset=os.path.join(path, "projects", uuid))
     # reimport_project(path, uuid)
     return