Carrier docstrings

pisa/carrier.py

@@ -10,6 +10,23 @@ logger = Logger("Carrier")
 
 
 class Receipt:
+    """
+    The ``Receipt`` class represent the interaction between the ``Carrier`` and ``bitcoind`` when broadcasting
+    transactions. It is used to signal whether or not a transaction has been successfully broadcast and why.
+
+    Args:
+        delivered (bool): whether or not the transaction has been successfully broadcast.
+        confirmations (int): the number of confirmations of the transaction to broadcast. In certain situations the
+            ``Carrier`` may fail to broadcast a transaction because it was already in the blockchain. This attribute
+            signals those situations.
+        reason (int): an error code describing why the transaction broadcast failed.
+
+    Returns:
+         ``Receipt``: A receipt describing whether or not the transaction was delivered. Notice that transactions
+         that are already on chain are flagged as delivered with a ``confirmations > 0`` whereas new transactions are so
+         with ``confirmations = 0``.
+    """
+
     def __init__(self, delivered, confirmations=0, reason=None):
         self.delivered = delivered
         self.confirmations = confirmations
@@ -17,8 +34,24 @@ class Receipt:
 
 
 class Carrier:
+    """
+    The ``Carrier`` is the class in charge of interacting with ``bitcoind`` to send/get transactions. It uses
+    ``Receipt`` objects to report about sending transactions.
+    """
+
     # NOTCOVERED
     def send_transaction(self, rawtx, txid):
+        """
+        Tries to send a given raw transaction to the Bitcoin network using ``bitcoind``.
+
+        Args:
+            rawtx (str): a (potentially) signed raw transaction ready to be broadcast.
+            txid  (str): the transaction id corresponding to ``rawtx``.
+
+        Returns:
+            ``Receipt``: A receipt reporting whether the transaction was successfully delivered or not and why.
+        """
+
         try:
             logger.info("Pushing transaction to the network", txid=txid, rawtx=rawtx)
             bitcoin_cli().sendrawtransaction(rawtx)
@@ -71,6 +104,17 @@ class Carrier:
 
     @staticmethod
     def get_transaction(txid):
+        """
+        Queries transaction data to ``bitcoind`` given a transaction id.
+
+        Args:
+            txid (str): a 32-byte hex-formatted string representing the transaction id.
+
+        Returns:
+            ``dict`` or ``None``: A dictionary with the transaction data if the transaction can be found on the chain.
+            Returns ``None`` otherwise.
+        """
+
         try:
             tx_info = bitcoin_cli().getrawtransaction(txid, 1)