From d85be4a8664af4740ae581f82457b5ffb9beea66 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jo=C3=A3o=20Gabriel=20Carvalho?= <jgcarvalho93@gmail.com>
Date: Thu, 4 May 2017 12:41:09 -0300
Subject: [PATCH] Add natspec to vestedToken.sol

---
 contracts/token/VestedToken.sol | 49 ++++++++++++++++++++++++++++-----
 1 file changed, 42 insertions(+), 7 deletions(-)

diff --git a/contracts/token/VestedToken.sol b/contracts/token/VestedToken.sol
index e563ba680..d2b4da196 100644
--- a/contracts/token/VestedToken.sol
+++ b/contracts/token/VestedToken.sol
@@ -6,8 +6,7 @@ import "./LimitedTransferToken.sol";
 
 /**
 * @title Vested token
-* @dev This tokens can be granted to a specific address after a determined
-amount of time.
+* @dev Tokens that can be vested for a group of addresses.
 */
 contract VestedToken is StandardToken, LimitedTransferToken {
 
@@ -25,9 +24,9 @@ contract VestedToken is StandardToken, LimitedTransferToken {
   * @dev Grant tokens to a specified address
   * @param _to address The address which the tokens will be granted to.
   * @param _value uint256 The amount of tokens to be granted.
-  * @param _start uint 64 The time of the begining of the grant.
-  * @param _cliff uint64 The time before the grant is enforceble.
-  * @param _vesting uint64 The time in which the tokens will be vested.
+  * @param _start uint64 Represents time of the begining of the grant.
+  * @param _cliff uint64 Represents the cliff period.
+  * @param _vesting uint64 Represents the vesting period.
   */
   function grantVestedTokens(
     address _to,
@@ -80,16 +79,18 @@ contract VestedToken is StandardToken, LimitedTransferToken {
  /**
  * @dev Check the amount of grants that an address has.
  * @param _holder address The holder of the grants.
- * @return A uint representing the index of the grant.
+ * @return A uint representing the total amount of grants.
  */
   function tokenGrantsCount(address _holder) constant returns (uint index) {
     return grants[_holder].length;
   }
 
   /**
-  * @dev 
+  * @dev Get all information about a specifc grant.
   * @param _holder address The address which will have its tokens revoked.
   * @param _grantId uint The id of the token grant.
+  * @return Returns all the values that represent a TokenGrant(address, value,
+     start, cliff and vesting) plus the vested value at the current time.
   */
   function tokenGrant(address _holder, uint _grantId) constant returns (address granter, uint256 value, uint256 vested, uint64 start, uint64 cliff, uint64 vesting) {
     TokenGrant grant = grants[_holder][_grantId];
@@ -103,6 +104,13 @@ contract VestedToken is StandardToken, LimitedTransferToken {
     vested = vestedTokens(grant, uint64(now));
   }
 
+  /**
+  * @dev Get the amount of vested tokens at a specifc time.
+  * @param grant TokenGrant The grant to be checked.
+  * @param time uint64 The time to be checked
+  * @return An uint representing the amount of vested tokens of a specifc grant
+  on specifc time.
+  */
   function vestedTokens(TokenGrant grant, uint64 time) private constant returns (uint256) {
     return calculateVestedTokens(
       grant.value,
@@ -113,6 +121,15 @@ contract VestedToken is StandardToken, LimitedTransferToken {
     );
   }
 
+  /**
+  * @dev Calculate amount of vested tokens at a specifc time.
+  * @param tokens uint256 The amount of tokens grantted.
+  * @param time uint64 The time to be checked
+  * @param start uint64 A time representing the begining of the grant
+  * @param _cliff uint64 Represents the cliff period.
+  * @param _vesting uint64 Represents the vesting period.
+  * @return An uint representing the amount of vested tokensof a specif grant.
+  */
   function calculateVestedTokens(
     uint256 tokens,
     uint256 time,
@@ -136,10 +153,22 @@ contract VestedToken is StandardToken, LimitedTransferToken {
     vestedTokens = vestedTokens.add(vestingTokens.mul(time.sub(cliff)).div(vesting.sub(cliff)));
   }
 
+  /**
+  * @dev Calculate the amount of non vested tokens at a specific time.
+  * @param grant TokenGrant The grant to be checked.
+  * @param time uint64 The time to be checked
+  * @return An uint representing the amount of non vested tokens of a specifc grant
+  on the passed time frame.
+  */
   function nonVestedTokens(TokenGrant grant, uint64 time) private constant returns (uint256) {
     return grant.value.sub(vestedTokens(grant, time));
   }
 
+  /**
+  * @dev Calculate the date when the holder can trasfer all its tokens
+  * @param holder address The address of the holder
+  * @return An uint representing the date of the last transferable tokens.
+  */
   function lastTokenIsTransferableDate(address holder) constant public returns (uint64 date) {
     date = uint64(now);
     uint256 grantIndex = grants[holder].length;
@@ -148,6 +177,12 @@ contract VestedToken is StandardToken, LimitedTransferToken {
     }
   }
 
+  /**
+  * @dev Calculate the total amount of transferable tokens of a holder at a given time
+  * @param holder address The address of the holder
+  * @param time uint64 The specific time.
+  * @return An uint representing a holder's total amount of transferable tokens.
+  */
   function transferableTokens(address holder, uint64 time) constant public returns (uint256 nonVested) {
     uint256 grantIndex = grants[holder].length;
     for (uint256 i = 0; i < grantIndex; i++) {