From 899b60c083c26f36b26962a0349531e57c70a97e Mon Sep 17 00:00:00 2001
From: Sergi Delgado Segura <sergi.delgado.s@gmail.com>
Date: Tue, 10 Dec 2019 11:33:01 +0100
Subject: [PATCH] Adds Builder docstrings

---
 pisa/builder.py | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/pisa/builder.py b/pisa/builder.py
index ac085df..5d39034 100644
--- a/pisa/builder.py
+++ b/pisa/builder.py
@@ -5,8 +5,29 @@ from pisa.appointment import Appointment
 
 
 class Builder:
+    """
+    The ``Builder`` class is in charge or reconstructing data loaded from the database and build the data structures
+    of the :mod:`Watcher <pisa.watcher>` and the :mod:`Responder <pisa.responder>`.
+    """
+
     @staticmethod
     def build_appointments(appointments_data):
+        """
+        Builds an appointments dictionary (``uuid: Appointment``) and a locator_uuid_map (``locator: uuid``) given a
+        dictionary of appointments from the database.
+
+        Args:
+            appointments_data (dict): a dictionary of dictionaries representing all the :mod:`Watcher <pisa.watcher>`
+                appointments stored in the database. The structure is as follows:
+
+                    ``{uuid: {locator: str, start_time: int, ...}, uuid: {locator:...}}``
+
+        Returns:
+            appointments, locator_uuid_map (tuple): A tuple with two dictionaries. ``appointments`` containing the
+            appointment information in :mod:`Appointment <pisa.appointment>` objects and ``locator_uuid_map``
+            containing a map of appointment (``uuid:locator``).
+        """
+
         appointments = {}
         locator_uuid_map = {}
 
@@ -24,6 +45,23 @@ class Builder:
 
     @staticmethod
     def build_jobs(jobs_data):
+        """
+        Builds a jobs dictionary (``uuid: Jobs``) and a tx_job_map (``penalty_txid: uuid``) given a dictionary of jobs
+        from the database.
+
+        Args:
+            jobs_data (dict): a dictionary of dictionaries representing all the :mod:`Responder <pisa.responder>` jobs
+                stored in the database. The structure is as follows:
+
+                    ``{uuid: {locator: str, dispute_txid: str, ...}, uuid: {locator:...}}``
+
+        Returns:
+            jobs, tx_job_map (tuple): A tuple with two dictionaries. ``jobs`` containing the jobs information in
+            :class:`Job <pisa.responder>` objects and a ``tx_job_map`` containing the map of jobs
+            (``penalty_txid: uuid``).
+
+        """
+
         jobs = {}
         tx_job_map = {}
 
@@ -41,6 +79,17 @@ class Builder:
 
     @staticmethod
     def build_block_queue(missed_blocks):
+        """
+        Builds a ``Queue`` of block hashes to initialize the :mod:`Watcher <pisa.watcher>` or the
+        :mod:`Responder <pisa.responder>` using backed up data.
+
+        Args:
+            missed_blocks (list): list of block hashes missed by the Watchtower (do to a crash or shutdown).
+
+        Returns:
+            block_queue (Queue): A `Queue` containing all the missed blocks hashes.
+        """
+
         block_queue = Queue()
 
         for block in missed_blocks: