Make small improvements to docstrings

apps/auctions/volume_matching.py

@@ -35,15 +35,16 @@ async def compute_bids(ctx, balances, bids, price):
 
     Parameters
     ----------
-    balances : {address -> {cointype -> balance}}
+    balances : dict of dict
+        Dictionary of the form: ``{address: {cointype: balance}}``.
         Address is a string representing
         the public address of the user.
         Cointype is a string.
         Now we only support two cointypes, 'eth' and 'erc20'.
         Balance is a FixedPoint number.
-    bids : [(address, volume)]
+    bids : list of tuple
         A list of bids.
-        Each bid is a list of two elements,
+        Each bid is a tuple of two elements ``(address, volume)``,
         the address of the owner and the volume of this bid.
         Address is a string and volume is a FixedPoint number.
         When volume is larger than zero, this bid is a buy bid,
@@ -59,10 +60,10 @@ async def compute_bids(ctx, balances, bids, price):
 
     Returns
     -------
-    buys : [(address, volume)]
-        List of valid buy orders.
-    sells : [(address, volume)]
-        List of valid sell orders.
+    buys : list of tuple
+        List of valid buy orders ``(address, volume)``.
+    sells : list of tuple
+        List of valid sell orders ``(address, volume)``.
         Since we have separated buy and sell bids,
         now every sell bid has volume larger than zero.
     """
@@ -72,6 +73,7 @@ async def compute_bids(ctx, balances, bids, price):
     fp_zero = FixedPoint(ctx, zero)
 
     used_balances = {}
+    # TODO for key in balances:
     for key in balances.keys():
         used_balances[key] = {
             "eth": create_clear_share(ctx, 0),
@@ -130,20 +132,22 @@ async def volume_matching(ctx, buys, sells):
 
     Parameters
     ----------
-    buys : [(address, volume)]
-        List of valid buy orders
-    sells : [(address, volume)]
-        List of valid sell orders
+    buys : list of tuple
+        List of valid buy orders. An order is a 2-tuple:
+        ``(address, volume)``.
+    sells : list of tuple
+        List of valid sell orders. An order is a 2-tuple:
+        ``(address, volume)``.
 
     Returns
     -------
-    matched_buys : [(address, volume)]
+    matched_buys : list of tuple
         The matched part of each buy orders.
-    matched_sells : [(address, volume)]
+    matched_sells : list of tuple
         The matched part of each sell orders.
-    res_buys : [(address, volume)]
+    res_buys : list of tuple
         The unmatched part of each buy orders.
-    res_sells : [(address, volume)]
+    res_sells : list of tuple
         The unmatched part of each sell orders.
     """
 
@@ -210,19 +214,21 @@ async def compute_new_balances(balances, matched_buys, matched_sells, price):
 
     Parameters
     ----------
-    balances : {address -> {cointype -> balance}}
-        Balances of users before matching
-    matched_buys : [(address, volume)]
-        List of matched buy bids
-    matched_sells : [(address, volume)]
-        List of matched sell bids
+    balances : dict of dict
+        Balances of users before matching.
+        The dict is of the form: ``{address: {cointype: balance}}``,
+        same as in the :func:`compute_bids` function.
+    matched_buys : list of tuple
+        List of matched buy bids.
+    matched_sells : list of tuple
+        List of matched sell bids.
     price: FixedPoint
         External market price
 
     Returns
     -------
-    balances : {address -> {cointype -> balance}}
-        Updated balances after matching
+    balances : dict of dict
+        Updated balances after matching.
     """
 
     for sell in matched_sells: