From 4ef86e6128277288595418db1bcd55b489ccc494 Mon Sep 17 00:00:00 2001
From: Greg Hysen <greg.hysen@gmail.com>
Date: Fri, 28 Jun 2019 03:17:53 -0700
Subject: [PATCH] Adding documentation to delegated stake mixin

---
 .../src/stake/MixinDelegatedStake.sol         | 17 +++++++++++---
 .../staking_pools/MixinStakingPoolRewards.sol | 23 ++++++++++++++++++-
 2 files changed, 36 insertions(+), 4 deletions(-)

diff --git a/contracts/staking/contracts/src/stake/MixinDelegatedStake.sol b/contracts/staking/contracts/src/stake/MixinDelegatedStake.sol
index 361afc869a..8e7c53a37d 100644
--- a/contracts/staking/contracts/src/stake/MixinDelegatedStake.sol
+++ b/contracts/staking/contracts/src/stake/MixinDelegatedStake.sol
@@ -103,7 +103,11 @@ contract MixinDelegatedStake is
     /// @param owner of Stake
     /// @param poolId Unique Id of staking pool to delegate stake to.
     /// @param amount of Stake to delegate.
-    function _delegateStake(address payable owner, bytes32 poolId, uint256 amount)
+    function _delegateStake(
+        address payable owner,
+        bytes32 poolId,
+        uint256 amount
+    )
         private
     {
         // take snapshot of parameters before any computation
@@ -129,8 +133,15 @@ contract MixinDelegatedStake is
         delegatedStakeByPoolId[poolId] = _delegatedStakeByPoolId._add(amount);
     }
 
-    // question - should we then return the amount withdrawn?
-    function _undelegateStake(address payable owner, bytes32 poolId, uint256 amount)
+    /// @dev Undelegates stake of `owner` from the staking pool with id `poolId`
+    /// @param owner of Stake
+    /// @param poolId Unique Id of staking pool to undelegate stake from.
+    /// @param amount of Stake to undelegate.
+    function _undelegateStake(
+        address payable owner,
+        bytes32 poolId,
+        uint256 amount
+    )
         private
     {
         // take snapshot of parameters before any computation
diff --git a/contracts/staking/contracts/src/staking_pools/MixinStakingPoolRewards.sol b/contracts/staking/contracts/src/staking_pools/MixinStakingPoolRewards.sol
index 3def7ce8e3..a9b785c929 100644
--- a/contracts/staking/contracts/src/staking_pools/MixinStakingPoolRewards.sol
+++ b/contracts/staking/contracts/src/staking_pools/MixinStakingPoolRewards.sol
@@ -220,6 +220,15 @@ contract MixinStakingPoolRewards is
         );
     }
 
+    /// @dev A member joins a staking pool.
+    /// This function increments the shadow balance of the member, along
+    /// with the total shadow balance of the pool. This ensures that
+    /// any rewards belonging to existing members will not be diluted.
+    /// @param poolId Unique Id of pool to join.
+    /// @param member The member to join. 
+    /// @param amountOfStakeToDelegate The stake to be delegated by `member` upon joining.
+    /// @param totalStakeDelegatedToPool The amount of stake currently delegated to the pool.
+    ///                                  This does not include `amountOfStakeToDelegate`.
     function _joinStakingPool(
         bytes32 poolId,
         address payable member,
@@ -229,7 +238,6 @@ contract MixinStakingPoolRewards is
         internal
     {
         // update delegator's share of reward pool
-        // note that this uses the snapshot parameters
         uint256 poolBalance = getBalanceOfMembersInStakingPoolRewardVault(poolId);
         uint256 buyIn = LibRewardMath._computeBuyInDenominatedInShadowAsset(
             amountOfStakeToDelegate,
@@ -237,12 +245,25 @@ contract MixinStakingPoolRewards is
             shadowRewardsByPoolId[poolId],
             poolBalance
         );
+
+        // the buy-in will be > 0 iff there exists a non-zero reward.
         if (buyIn > 0) {
             shadowRewardsInPoolByOwner[member][poolId] = shadowRewardsInPoolByOwner[member][poolId]._add(buyIn);
             shadowRewardsByPoolId[poolId] = shadowRewardsByPoolId[poolId]._add(buyIn);
         }
     }
 
+    /// @dev A member leaves a staking pool.
+    /// This function decrements the shadow balance of the member, along
+    /// with the total shadow balance of the pool. This ensures that
+    /// any rewards belonging to co-members will not be inflated.
+    /// @param poolId Unique Id of pool to leave.
+    /// @param member The member to leave. 
+    /// @param amountOfStakeToUndelegate The stake to be undelegated by `member` upon leaving.
+    /// @param totalStakeDelegatedToPoolByMember The amount of stake currently delegated to the pool by the member.
+    ///                                          This includes `amountOfStakeToUndelegate`.
+    /// @param totalStakeDelegatedToPool The total amount of stake currently delegated to the pool, across all members.
+    ///                                  This includes `amountOfStakeToUndelegate`.
     function _leaveStakingPool(
         bytes32 poolId,
         address payable member,