spellcheck comments

contracts/LiquidPledging.sol

@@ -91,7 +91,7 @@ contract LiquidPledging is LiquidPledgingBase {
     /// @param amount Quantity of value that's being moved
     /// @param idReceiver Destination of the value, can be a giver sending to 
     ///  a giver or a delegate, a delegate to another delegate or a project 
-    ///  to precommit it to that project
+    ///  to pre-commit it to that project
     function transfer(
         uint64 idSender,
         uint64 idPledge,
@@ -168,10 +168,10 @@ contract LiquidPledging is LiquidPledgingBase {
 
                 // If the receiver is already part of the delegate chain and is
                 // before the sender, then the sender and all of the other
-                // delegates after the RECEIVER are revomved from the chain,
+                // delegates after the RECEIVER are removed from the chain,
-                // this is interesting because the delegate undelegates from the
+                // this is interesting because the delegate is removed from the
-                // delegates that delegated to this delegate... game theory
+                // delegates that delegated to this delegate. Are there game theory
-                // issues? should this be allowed
+                // issues? should this be allowed?
                 } else if (receiverDIdx <= senderDIdx) {
                     undelegate(
                         idPledge,
@@ -182,7 +182,7 @@ contract LiquidPledging is LiquidPledgingBase {
                 return;
             }
 
-            // If the delegate wants to support a project, they undelegate all
+            // If the delegate wants to support a project, they remove all
             // the delegates after them in the chain and choose a project
             if (receiver.adminType == PledgeAdminType.Project) {
                 idPledge = undelegate(
@@ -285,7 +285,7 @@ contract LiquidPledging is LiquidPledgingBase {
         CancelProject(idProject);
     }
 
-    /// @notice Method called to cancel specfic pledge.
+    /// @notice Method called to cancel specific pledge.
     /// @param idPledge Id of the pledge that should be canceled.
     /// @param amount Quantity of Ether that wants to be rolled back.
     function cancelPledge(uint64 idPledge, uint amount) {
@@ -320,7 +320,7 @@ contract LiquidPledging is LiquidPledgingBase {
     ///  using the D64 bitmask
     /// @param idReceiver Destination of the value, can be a giver sending
     ///  to a giver or a delegate or a delegate to another delegate or a
-    ///  project to precommit it to that project
+    ///  project to pre-commit it to that project
     function mTransfer(
         uint64 idSender,
         uint[] pledgesAmounts,
@@ -360,7 +360,7 @@ contract LiquidPledging is LiquidPledgingBase {
         }
     }
 
-    /// @notice `mCancelPayment` allows for multiple pledges to be cancelled
+    /// @notice `mCancelPayment` allows for multiple pledges to be canceled
     ///  efficiently
     /// @param amount An array of pledge amounts and IDs which are extrapolated
     ///  using the D64 bitmask
@@ -390,11 +390,11 @@ contract LiquidPledging is LiquidPledgingBase {
 ///////
 
     /// @notice `transferOwnershipToProject` allows for the transfer of
-    ///  ownership to the project, but it can also be called to undelegate
+    ///  ownership to the project, but it can also be called to un-delegate
     ///  everyone by setting one's own id for the idReceiver
     /// @param idPledge Id of the pledge to be transfered.
     /// @param amount Quantity of value that's being transfered
-    /// @param idReceiver The new owner of the project (or self to undelegate)
+    /// @param idReceiver The new owner of the project (or self to un-delegate)
     function transferOwnershipToProject(
         uint64 idPledge,
         uint amount,
@@ -403,7 +403,7 @@ contract LiquidPledging is LiquidPledgingBase {
         Pledge storage n = findPledge(idPledge);
 
         // Ensure that the pledge is not already at max pledge depth
-        // and the project has not been cancelled
+        // and the project has not been canceled
         require(getPledgeLevel(n) < MAX_INTERPROJECT_LEVEL);
         require(!isProjectCanceled(idReceiver));
 
@@ -462,7 +462,9 @@ contract LiquidPledging is LiquidPledgingBase {
         Pledge storage n = findPledge(idPledge);
 
         require(n.delegationChain.length < MAX_DELEGATES);
-        uint64[] memory newDelegationChain = new uint64[](n.delegationChain.length + 1);
+        uint64[] memory newDelegationChain = new uint64[](
+            n.delegationChain.length + 1
+        );
         for (uint i = 0; i<n.delegationChain.length; i++) {
             newDelegationChain[i] = n.delegationChain[i];
         }
@@ -492,7 +494,9 @@ contract LiquidPledging is LiquidPledgingBase {
         uint q
     ) internal returns (uint64){
         Pledge storage n = findPledge(idPledge);
-        uint64[] memory newDelegationChain = new uint64[](n.delegationChain.length - q);
+        uint64[] memory newDelegationChain = new uint64[](
+            n.delegationChain.length - q
+        );
         for (uint i=0; i<n.delegationChain.length - q; i++) {
             newDelegationChain[i] = n.delegationChain[i];
         }
@@ -514,7 +518,7 @@ contract LiquidPledging is LiquidPledgingBase {
     /// @dev This function should potentially be named more specifically.
     /// @param idPledge Id of the pledge that will be assigned.
     /// @param amount Quantity of value this pledge leader would be assigned.
-    /// @param idReceiver The project this pledge will potentialy 
+    /// @param idReceiver The project this pledge will potentially 
     ///  be assigned to.
     function proposeAssignProject(
         uint64 idPledge,
@@ -578,12 +582,12 @@ contract LiquidPledging is LiquidPledgingBase {
 
         Pledge storage n = findPledge(idPledge);
 
-        // Check to make sure this pledge hasnt already been used 
+        // Check to make sure this pledge hasn't already been used 
         // or is in the process of being used
         if (n.paymentState != PaymentState.Pledged)
             return idPledge;
 
-        // First send to a project if it's proposed and commited
+        // First send to a project if it's proposed and committed
         if ((n.intendedProject > 0) && ( getTime() > n.commitTime)) {
             uint64 oldPledge = findOrCreatePledge(
                 n.owner,
@@ -621,7 +625,7 @@ contract LiquidPledging is LiquidPledgingBase {
     ///  Specifically what this does in relation to the plugin is something
     ///  that largely depends on the functions of that plugin. This function
     ///  is generally called in pairs, once before, and once after a transfer.
-    /// @param before This toggle determines whether the plugin call is occuring
+    /// @param before This toggle determines whether the plugin call is occurring
     ///  before or after a transfer.
     /// @param adminId This should be the Id of the *trusted* individual
     ///  who has control over this plugin.

contracts/LiquidPledgingBase.sol

@@ -58,9 +58,13 @@ contract LiquidPledgingBase {
         uint amount;
         uint64 owner; // PledgeAdmin
         uint64[] delegationChain; // list of index numbers
-        uint64 intendedProject; // TODO change the name only used for when delegates are precommiting to a project
+        // TODO change the name only used for when delegates are 
-        uint64 commitTime;  // When the intendedProject will become the owner
+        // pre-committing to a project
-        uint64 oldPledge; // this points to the Pledge[] index that the Pledge was derived from
+        uint64 intendedProject; 
+        // When the intendedProject will become the owner
+        uint64 commitTime;
+        // this points to the Pledge[] index that the Pledge was derived from  
+        uint64 oldPledge; 
         PaymentState paymentState;
     }
 
@@ -68,7 +72,8 @@ contract LiquidPledgingBase {
     PledgeAdmin[] admins; //The list of pledgeAdmins 0 means there is no admin
     Vault public vault;
 
-    // this mapping allows you to search for a specific pledge's index number by the hash of that pledge
+    // this mapping allows you to search for a specific pledge's 
+    // index number by the hash of that pledge
     mapping (bytes32 => uint64) hPledge2idx;//TODO Fix typo
 
 
@@ -87,7 +92,8 @@ contract LiquidPledgingBase {
 // Constructor
 //////
 
-    /// @notice The Constructor creates the `LiquidPledgingBase` on the blockchain
+    /// @notice The Constructor creates the `LiquidPledgingBase` 
+    ///  on the blockchain
     /// @param _vault The vault where ETH backing this pledge is stored
     function LiquidPledgingBase(address _vault) {
         admins.length = 1; // we reserve the 0 admin
@@ -104,8 +110,13 @@ contract LiquidPledgingBase {
     /// @param name This is the name used to identify the giver.
     /// @param url This is a link to the givers profile or a representative site.
     /// @param commitTime Set the default commit time period for this giver.
-    /// @param plugin This is givers liquid pledge plugin allowing for extended functionality.
+    /// @param plugin This is givers liquid pledge plugin allowing for 
-    function addGiver(string name, string url, uint64 commitTime, ILiquidPledgingPlugin plugin
+    ///  extended functionality.
+    function addGiver(
+        string name,
+        string url,
+        uint64 commitTime,
+        ILiquidPledgingPlugin plugin
     ) returns (uint64 idGiver) {
 
         idGiver = uint64(admins.length);
@@ -163,9 +174,9 @@ contract LiquidPledgingBase {
         string url,
         uint64 commitTime,
         ILiquidPledgingPlugin plugin
-    ) returns (uint64 idDelegate) { //TODO return index number
+    ) returns (uint64 idxDelegate) { //TODO return index number
 
-        idDelegate = uint64(admins.length);
+        idxDelegate = uint64(admins.length);
 
         admins.push(PledgeAdmin(
             PledgeAdminType.Delegate,
@@ -177,10 +188,10 @@ contract LiquidPledgingBase {
             false,
             plugin));
 
-        DelegateAdded(idDelegate);
+        DelegateAdded(idxDelegate);
     }
 
-    event DelegateAdded(uint64 indexed idDelegate);
+    event DelegateAdded(uint64 indexed idxDelegate);
 
     /// @notice `updateDelegate` allows for basic update operation to change the address,
     ///  name or commitTime associated with a specific delegate.
@@ -192,22 +203,22 @@ contract LiquidPledgingBase {
     /// @param newUrl This is a link to the delegates profile or a representative site.
     /// @param newCommitTime Set the default commit time period for this giver.
     function updateDelegate(
-        uint64 idDelegate,
+        uint64 idxDelegate,
         address newAddr,
         string newName,
         string newUrl,
         uint64 newCommitTime) {
-        PledgeAdmin storage delegate = findAdmin(idDelegate);
+        PledgeAdmin storage delegate = findAdmin(idxDelegate);
         require(delegate.adminType == PledgeAdminType.Delegate);
         require(delegate.addr == msg.sender);
         delegate.addr = newAddr;
         delegate.name = newName;
         delegate.url = newUrl;
         delegate.commitTime = newCommitTime;
-        DelegateUpdated(idDelegate);
+        DelegateUpdated(idxDelegate);
     }
 
-    event DelegateUpdated(uint64 indexed idDelegate);
+    event DelegateUpdated(uint64 indexed idxDelegate);
 
     /// @notice `addProject` Creates a project and adds it to the list of admins.
     /// @param name This is the name used to identify the project.
@@ -313,15 +324,15 @@ contract LiquidPledgingBase {
     /// @notice `getPledgeDelegate` returns a single delegate given the pledge ID
     ///  and the delegate ID.
     /// @param idPledge The ID internally representing the pledge.
-    /// @param idDelegate The ID internally representing the delegate.
+    /// @param idxDelegate The ID internally representing the delegate.
-    function getPledgeDelegate(uint64 idPledge, uint idDelegate) constant returns(
+    function getPledgeDelegate(uint64 idPledge, uint idxDelegate) constant returns(
-        uint64 idDelegate,
+        uint64 idxDelegate,
         address addr,
         string name
     ) {
         Pledge storage n = findPledge(idPledge);
-        idDelegate = n.delegationChain[idDelegate - 1];
+        idxDelegate = n.delegationChain[idxDelegate - 1];
-        PledgeAdmin storage delegate = findAdmin(idDelegate);
+        PledgeAdmin storage delegate = findAdmin(idxDelegate);
         addr = delegate.addr;
         name = delegate.name;
     }
@@ -361,10 +372,16 @@ contract LiquidPledgingBase {
 // Private methods
 ///////
 
-    /// @notice All pledges technically exist... but if the pledge hasn't been
+    /// @notice All pledges technically exist. If the pledge hasn't been
-    ///  created in this system yet then it wouldn't be in the hash array
+    ///  created in this system yet it simply isn't in the hash array
-    ///  hPledge2idx[]; this creates a Pledge with and amount of 0 if one is not
+    ///  hPledge2idx[] yet; this creates a Pledge with an initial amount of 0 if one is not
-    ///  created already...
+    ///  created already. Otherwise 
+    /// @param owner The owner of the pledge being looked up.
+    /// @param delegationChain The array of all delegates.
+    /// @param intendedProject The intended project is the project this pledge will Fund.
+    /// @param oldPledge This value is used to store the pledge the current pledge 
+    ///  is "coming from."
+    /// @param paid Based on the payment state this shows whether the pledge has been paid.
     function findOrCreatePledge(
         uint64 owner,
         uint64[] delegationChain,
@@ -383,11 +400,17 @@ contract LiquidPledgingBase {
         return idx;
     }
 
+    /// @notice `findAdmin` is a basic getter to return a 
+    ///  specific admin (giver, delegate, or project)
+    /// @param idAdmin The admin ID to lookup.
     function findAdmin(uint64 idAdmin) internal returns (PledgeAdmin storage) {
         require(idAdmin < admins.length);
         return admins[idAdmin];
     }
 
+    /// @notice `findPledge` is a basic getter to return a 
+    ///  specific pledge 
+    /// @param idPledge The admin ID to pledge.
     function findPledge(uint64 idPledge) internal returns (Pledge storage) {
         require(idPledge < pledges.length);
         return pledges[idPledge];
@@ -396,25 +419,32 @@ contract LiquidPledgingBase {
     // a constant for the case that a delegate is requested that is not a delegate in the system
     uint64 constant  NOTFOUND = 0xFFFFFFFFFFFFFFFF;
 
-    // helper function that searches the delegationChain fro a specific delegate and
+    /// @notice `getDelegateIdx` is a helper function that searches the delegationChain
-    // level of delegation returns their idx in the delegation chain which reflect their level of authority
+    ///  for a specific delegate and level of delegation returns their idx in the 
-    function getDelegateIdx(Pledge n, uint64 idDelegate) internal returns(uint64) {
+    ///  delegation chain which reflect their level of authority. Returns MAX uint64
+    ///  if no delegate is found.
+    /// @param n The pledge that will be searched.
+    /// @param idxDelegate The internal ID of the delegate that's searched for.
+    function getDelegateIdx(Pledge n, uint64 idxDelegate) internal returns(uint64) {
         for (uint i=0; i<n.delegationChain.length; i++) {
-            if (n.delegationChain[i] == idDelegate) return uint64(i);
+            if (n.delegationChain[i] == idxDelegate) return uint64(i);
         }
         return NOTFOUND;
     }
  
-    // helper function that returns the pledge level solely to check that transfers
+    /// @notice `getPledgeLevel` is a helper function that returns the pledge "depth"
-    // between Projects not violate MAX_INTERPROJECT_LEVEL
+    ///  which can be used to check that transfers between Projects 
+    ///  not violate MAX_INTERPROJECT_LEVEL
+    /// @param n The pledge that will be searched.
     function getPledgeLevel(Pledge n) internal returns(uint) {
         if (n.oldPledge == 0) return 0; //changed
         Pledge storage oldN = findPledge(n.oldPledge);
         return getPledgeLevel(oldN) + 1;
     }
 
-    // helper function that returns the max commit time of the owner and all the
+    /// @notice  `maxCommitTime` is a helper function that returns the maximum
-    // delegates
+    ///  commit time of the owner and all the delegates.
+    /// @param n The pledge that will be searched.
     function maxCommitTime(Pledge n) internal returns(uint commitTime) {
         PledgeAdmin storage m = findAdmin(n.owner);
         commitTime = m.commitTime;
@@ -425,8 +455,9 @@ contract LiquidPledgingBase {
         }
     }
 
-    // helper function that returns the project level solely to check that there
+    /// @notice `getProjectLevel` is a helper function that returns the project
-    // are not too many Projects that violate MAX_SUBCAMPAIGNS_LEVEL
+    ///  level which can be used to check that there are not too many Projects
+    ///  that violate MAX_SUBCAMPAIGNS_LEVEL.
     function getProjectLevel(PledgeAdmin m) internal returns(uint) {
         assert(m.adminType == PledgeAdminType.Project);
         if (m.parentProject == 0) return(1);
@@ -434,6 +465,9 @@ contract LiquidPledgingBase {
         return getProjectLevel(parentNM);
     }
 
+    /// @notice `isProjectCanceled` is a basic helper function to check if
+    ///  a project has been cancelled.
+    /// @param projectId The internal id of the project to lookup.
     function isProjectCanceled(uint64 projectId) constant returns (bool) {
         PledgeAdmin storage m = findAdmin(projectId);
         if (m.adminType == PledgeAdminType.Giver) return false;
@@ -443,8 +477,9 @@ contract LiquidPledgingBase {
         return isProjectCanceled(m.parentProject);
     }
 
-    // @notice A helper function for canceling projects
+    /// @notice `getOldestPledgeNotCanceled` is a helper function to get the oldest pledge
-    // @param idPledge the pledge that may or may not be canceled
+    ///  that hasn't been cancelled recursively.
+    /// @param idPledge The starting place to lookup the pledges from
     function getOldestPledgeNotCanceled(uint64 idPledge) internal constant returns(uint64) { //todo rename
         if (idPledge == 0) return 0;
         Pledge storage n = findPledge(idPledge);
@@ -458,6 +493,12 @@ contract LiquidPledgingBase {
         return getOldestPledgeNotCanceled(n.oldPledge);
     }
 
+    /// @notice `checkAdminOwner` is a helper function designed to throw
+    ///  an error code if the user is not an admin. As PledgeAdmin is an
+    ///  an internal structure this basically works like a modifier check
+    ///  would however using internal data.
+    /// @dev Looking into whether this can be done with a modifier would be good
+    /// @param m A PledgeAdmin structure object.
     function checkAdminOwner(PledgeAdmin m) internal constant {
         require((msg.sender == m.addr) || (msg.sender == address(m.plugin)));
     }