more docs

dex/order/order.go

@@ -154,7 +154,7 @@ type Order interface {
 	// in the asset package.
 	Quote() uint32
 
-	// IsSell indicates the the order is selling the base asset (false indicates
+	// IsSell indicates if the order is selling the base asset (false indicates
 	// selling the quote asset). This helps identify the asset of the backing
 	// coins returned by CoinIDs(). Note that a cancel order will return false.
 	IsSell() bool
@@ -377,10 +377,12 @@ func (o *MarketOrder) Remaining() uint64 {
 	return o.Quantity - o.Filled
 }
 
+// IsSell indicates if the order is selling the base asset.
 func (o *MarketOrder) IsSell() bool {
 	return o.Sell
 }
 
+// CoinIDs returns the order's backing coins.
 func (o *MarketOrder) CoinIDs() []CoinID {
 	return o.Coins
 }
@@ -460,14 +462,11 @@ func (o *LimitOrder) Price() uint64 {
 	return o.Rate
 }
 
+// IsSell indicates if the order is selling the base asset.
 func (o *LimitOrder) IsSell() bool {
 	return o.Sell
 }
 
-// func (o *LimitOrder) Coins() []CoinID {
-// 	return o.Coins()
-// }
-
 // CancelOrder defines a cancel order in terms of an order Prefix and the ID of
 // the order to be canceled.
 type CancelOrder struct {
@@ -531,10 +530,12 @@ func (o *CancelOrder) FilledAmt() uint64 {
 	return 0
 }
 
+// IsSell is always false for a CancelOrder.
 func (o *CancelOrder) IsSell() bool {
 	return false
 }
 
+// CoinIDs always returns a nil slice for a CancelOrder.
 func (o *CancelOrder) CoinIDs() []CoinID {
 	return nil
 }

server/coinlock/coinlocker.go

@@ -12,16 +12,23 @@ type CoinID = order.CoinID
 // CoinLockChecker provides the ability to check if a coin or an order's backing
 // coins are locked.
 type CoinLockChecker interface {
+	// CoinLocked indicates if a coin is locked.
 	CoinLocked(coin CoinID) bool
+	// OrderCoinsLocked returns all coins locked by an order.
 	OrderCoinsLocked(oid order.OrderID) []CoinID
 }
 
 // CoinLocker provides the ability to lock, unlock and check lock status of
 // coins.
 type CoinLocker interface {
 	CoinLockChecker
+	// UnlockOrderCoins unlocks all locked coins associated with an order.
 	UnlockOrderCoins(oid order.OrderID)
+	// LockOrdersCoins locks all of the coins associated with multiple orders.
 	LockOrdersCoins(orders []order.Order)
+	// LockCoins locks coins associated with certain orders. The input is
+	// defined as a map of OrderIDs to a CoinID slice since it is likely easiest
+	// for the caller to construct the input in this way.
 	LockCoins(orderCoins map[order.OrderID][]CoinID)
 }
 
@@ -59,7 +66,9 @@ func (cl *MasterCoinLocker) OrderCoinsLocked(oid order.OrderID) []CoinID {
 		return coins
 	}
 
-	// TODO: merge?
+	// TODO: Figure out how we will handle the evolving coinIDs for an order
+	// with partial fills and decide how to merge the results of both swap and
+	// book locks.
 	return cl.bookLock.OrderCoinsLocked(oid)
 }
 
@@ -77,14 +86,17 @@ type bookLocker struct {
 	*MasterCoinLocker
 }
 
+// LockOrdersCoins locks all coins for the given orders.
 func (bl *bookLocker) LockOrdersCoins(orders []order.Order) {
 	bl.bookLock.LockOrdersCoins(orders)
 }
 
+// LockOrdersCoins locks coins associated with certain orders.
 func (bl *bookLocker) LockCoins(orderCoins map[order.OrderID][]CoinID) {
 	bl.bookLock.LockCoins(orderCoins)
 }
 
+// UnlockOrderCoins unlocks all locked coins associated with an order.
 func (bl *bookLocker) UnlockOrderCoins(oid order.OrderID) {
 	bl.bookLock.UnlockOrderCoins(oid)
 }
@@ -95,14 +107,17 @@ type swapLocker struct {
 	*MasterCoinLocker
 }
 
+// LockOrdersCoins locks all coins for the given orders.
 func (bl *swapLocker) LockOrdersCoins(orders []order.Order) {
 	bl.swapLock.LockOrdersCoins(orders)
 }
 
+// LockOrdersCoins locks coins associated with certain orders.
 func (bl *swapLocker) LockCoins(orderCoins map[order.OrderID][]CoinID) {
 	bl.swapLock.LockCoins(orderCoins)
 }
 
+// UnlockOrderCoins unlocks all locked coins associated with an order.
 func (bl *swapLocker) UnlockOrderCoins(oid order.OrderID) {
 	bl.swapLock.UnlockOrderCoins(oid)
 }