From dce7b4d39ed0e351baad505c028e966a51e4a0de Mon Sep 17 00:00:00 2001
From: Sergi Delgado Segura <sergi.delgado.s@gmail.com>
Date: Thu, 23 Jan 2020 19:00:55 +0100
Subject: [PATCH] Adds missing tools docs

---
 common/tools.py | 57 +++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 53 insertions(+), 4 deletions(-)

diff --git a/common/tools.py b/common/tools.py
index ec02451..8e0617c 100644
--- a/common/tools.py
+++ b/common/tools.py
@@ -12,7 +12,7 @@ def check_sha256_hex_format(value):
         value(:mod:`str`): the value to be checked.
 
     Returns:
-        :mod:`bool`: Whether or not the value matches the format.
+        :obj:`bool`: Whether or not the value matches the format.
     """
     return isinstance(value, str) and re.match(r"^[0-9A-Fa-f]{64}$", value) is not None
 
@@ -25,7 +25,7 @@ def check_locator_format(value):
         value(:mod:`str`): the value to be checked.
 
     Returns:
-        :mod:`bool`: Whether or not the value matches the format.
+        :obj:`bool`: Whether or not the value matches the format.
     """
     return isinstance(value, str) and re.match(r"^[0-9A-Fa-f]{32}$", value) is not None
 
@@ -36,19 +36,44 @@ def compute_locator(tx_id):
     Args:
         tx_id (:obj:`str`): the transaction id used to compute the locator.
     Returns:
-       (:obj:`str`): The computed locator.
+       :obj:`str`: The computed locator.
     """
 
     return tx_id[:LOCATOR_LEN_HEX]
 
 
 def setup_data_folder(data_folder, logger):
+    """
+    Create a data folder for either the client or the server side if the folder does not exists.
+
+    Args:
+        data_folder (:obj:`str`): the path of the folder
+        logger (:obj: `Logger <common.logger.Logger>`): a logger instance to notify about the folder creation.
+    """
+
     if not os.path.isdir(data_folder):
         logger.info("Data folder not found. Creating it")
         os.makedirs(data_folder, exist_ok=True)
 
 
 def check_conf_fields(conf_fields):
+    """
+    Checks that the provided configuration field have the right type.
+
+    Args:
+        conf_fields (:obj:`dict`): a dictionary populated with the configuration file params and the expected types.
+            The format is as follows:
+
+            {"field0": {"value": value_from_conf_file, "type": expected_type, ...}}
+
+    Returns:
+        :obj:`dict`: A dictionary with the same keys as the provided one, but containing only the "value" field as value
+        if the provided ``conf_fields`` where correct.
+
+    Raises:
+        ValueError: If any of the dictionary elements does not have the expected type
+    """
+
     conf_dict = {}
 
     for field in conf_fields:
@@ -65,14 +90,38 @@ def check_conf_fields(conf_fields):
 
 
 def extend_paths(base_path, config_fields):
+    """
+    Extends the relative paths of a given ``config_fields`` dictionary with a diven ``base_path``.
+
+    Paths in the config file are based on DATA_PATH, this method extends them so they are all absolute.
+
+    Args:
+        base_path (:obj:`str`): the base path to prepend the other paths.
+        config_fields (:obj:`dict`): a dictionary of configuration fields containing a ``path`` flag, as follows:
+            {"field0": {"value": value_from_conf_file, "path": True, ...}}
+
+    Returns:
+        :obj:`dict`: A ``config_fields`` with the flagged paths updated.
+    """
+
     for key, field in config_fields.items():
-        if field.get("path"):
+        if field.get("path") is True:
             config_fields[key]["value"] = base_path + config_fields[key]["value"]
 
     return config_fields
 
 
 def setup_logging(log_file_path, log_name_prefix):
+    """
+    Setups a couple of loggers (console and file) given a prefix and a file path. The log names are:
+
+    prefix | _file_log and prefix | _console_log
+
+    Args:
+        log_file_path (:obj:`str`): the path of the file to output the file log.
+        log_name_prefix (:obj:`str`): the prefix to identify the log.
+    """
+
     if not isinstance(log_file_path, str):
         print(log_file_path)
         raise ValueError("Wrong log file path.")