From f6f91298f00b69bb58a3a3f52477d9a4b0e83b21 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Gabriel=20Carvalho?= Date: Wed, 3 May 2017 18:16:28 -0300 Subject: [PATCH] Add natspec to all remaing contracts, except for vestedToken.sol --- contracts/token/BasicToken.sol | 22 +++++++++++---- contracts/token/CrowdsaleToken.sol | 31 +++++++++++++------- contracts/token/ERC20.sol | 6 ++-- contracts/token/ERC20Basic.sol | 8 +++--- contracts/token/LimitedTransferToken.sol | 36 ++++++++++++++++-------- contracts/token/MintableToken.sol | 22 ++++++++++----- contracts/token/SimpleToken.sol | 15 ++++++---- contracts/token/StandardToken.sol | 26 ++++++++++++++--- contracts/token/VestedToken.sol | 30 ++++++++++++++++++++ 9 files changed, 144 insertions(+), 52 deletions(-) diff --git a/contracts/token/BasicToken.sol b/contracts/token/BasicToken.sol index 81192144b..8b0cb3147 100644 --- a/contracts/token/BasicToken.sol +++ b/contracts/token/BasicToken.sol @@ -5,17 +5,17 @@ import './ERC20Basic.sol'; import '../SafeMath.sol'; -/* - * Basic token - * Basic version of StandardToken, with no allowances +/** + * @title Basic token + * @dev Basic version of StandardToken, with no allowances */ contract BasicToken is ERC20Basic { using SafeMath for uint; mapping(address => uint) balances; - /* - * Fix for the ERC20 short address attack + /** + * @dev Fix for the ERC20 short address attack */ modifier onlyPayloadSize(uint size) { if(msg.data.length < size + 4) { @@ -24,14 +24,24 @@ contract BasicToken is ERC20Basic { _; } + /** + * @dev transfer token for a specified address + * @param _to address The address which you want to transfer to + * @param _value uint the amout to be transfered + */ function transfer(address _to, uint _value) onlyPayloadSize(2 * 32) { balances[msg.sender] = balances[msg.sender].sub(_value); balances[_to] = balances[_to].add(_value); Transfer(msg.sender, _to, _value); } + /** + * @dev Function to get the balance of the specified address + * @param _owner address The address you wish to get the balance from + * @return An uint representing the amout owned by the passed address + */ function balanceOf(address _owner) constant returns (uint balance) { return balances[_owner]; } - + } diff --git a/contracts/token/CrowdsaleToken.sol b/contracts/token/CrowdsaleToken.sol index fad970c1e..df63e6bab 100644 --- a/contracts/token/CrowdsaleToken.sol +++ b/contracts/token/CrowdsaleToken.sol @@ -5,28 +5,36 @@ import "./StandardToken.sol"; /* - * CrowdsaleToken + * @title CrowdsaleToken * - * Simple ERC20 Token example, with crowdsale token creation - * IMPORTANT NOTE: do not use or deploy this contract as-is. - * It needs some changes to be production ready. + * @dev Simple ERC20 Token example, with crowdsale token creation + * @dev IMPORTANT NOTE: do not use or deploy this contract as-is. It + needs some changes to be production ready. */ contract CrowdsaleToken is StandardToken { string public constant name = "CrowdsaleToken"; string public constant symbol = "CRW"; uint public constant decimals = 18; - // replace with your fund collection multisig address - address public constant multisig = 0x0; + // replace with your fund collection multisig address + address public constant multisig = 0x0; - // 1 ether = 500 example tokens + // 1 ether = 500 example tokens uint public constant PRICE = 500; + /** + * @dev A function that recieves ether and send the equivalent amount of + the token to the msg.sender + */ function () payable { createTokens(msg.sender); } - + + /** + * @dev Function to create tokens and send to the specified address + * @param recipient address The address which will recieve the new tokens. + */ function createTokens(address recipient) payable { if (msg.value == 0) { throw; @@ -41,8 +49,11 @@ contract CrowdsaleToken is StandardToken { throw; } } - - // replace this with any other price function + + /** + * @dev replace this with any other price function + * @return The price per unit of token. + */ function getPrice() constant returns (uint result) { return PRICE; } diff --git a/contracts/token/ERC20.sol b/contracts/token/ERC20.sol index 2116ab95b..57b213edf 100644 --- a/contracts/token/ERC20.sol +++ b/contracts/token/ERC20.sol @@ -4,9 +4,9 @@ pragma solidity ^0.4.8; import './ERC20Basic.sol'; -/* - * ERC20 interface - * see https://github.com/ethereum/EIPs/issues/20 +/** + * @title ERC20 interface + * @dev see https://github.com/ethereum/EIPs/issues/20 */ contract ERC20 is ERC20Basic { function allowance(address owner, address spender) constant returns (uint); diff --git a/contracts/token/ERC20Basic.sol b/contracts/token/ERC20Basic.sol index 809addebf..11185765b 100644 --- a/contracts/token/ERC20Basic.sol +++ b/contracts/token/ERC20Basic.sol @@ -1,10 +1,10 @@ pragma solidity ^0.4.8; -/* - * ERC20Basic - * Simpler version of ERC20 interface - * see https://github.com/ethereum/EIPs/issues/20 +/** + * @title ERC20Basic + * @dev Simpler version of ERC20 interface + * @dev see https://github.com/ethereum/EIPs/issues/20 */ contract ERC20Basic { uint public totalSupply; diff --git a/contracts/token/LimitedTransferToken.sol b/contracts/token/LimitedTransferToken.sol index 91d5309e0..6dcd0df4b 100644 --- a/contracts/token/LimitedTransferToken.sol +++ b/contracts/token/LimitedTransferToken.sol @@ -2,20 +2,16 @@ pragma solidity ^0.4.8; import "./ERC20.sol"; -/* +/** -LimitedTransferToken defines the generic interface and the implementation +* @title LimitedTransferToken + +* @dev LimitedTransferToken defines the generic interface and the implementation to limit token transferability for different events. - It is intended to be used as a base class for other token contracts. - -Overwriting transferableTokens(address holder, uint64 time) is the way to provide -the specific logic for limiting token transferability for a holder over time. - LimitedTransferToken has been designed to allow for different limiting factors, this can be achieved by recursively calling super.transferableTokens() until the base class is hit. For example: - function transferableTokens(address holder, uint64 time) constant public returns (uint256) { return min256(unlockedTokens, super.transferableTokens(holder, time)); } @@ -26,23 +22,39 @@ https://github.com/OpenZeppelin/zeppelin-solidity/blob/master/contracts/token/Ve */ contract LimitedTransferToken is ERC20 { - // Checks whether it can transfer or otherwise throws. + + /** + * @dev Checks whether it can transfer or otherwise throws. + */ modifier canTransfer(address _sender, uint _value) { if (_value > transferableTokens(_sender, uint64(now))) throw; _; } - // Checks modifier and allows transfer if tokens are not locked. + /** + * @dev Checks modifier and allows transfer if tokens are not locked. + * @param _to address The address that will recieve the tokens + * @param _value uint The amount of tokens to be transfered + */ function transfer(address _to, uint _value) canTransfer(msg.sender, _value) { return super.transfer(_to, _value); } - // Checks modifier and allows transfer if tokens are not locked. + /** + * @dev Checks modifier and allows transfer if tokens are not locked. + * @param _from address The address that will send the tokens. + * @param _to address The address that will recieve the tokens. + * @param _value uint The amount of tokens to be transfered. + */ function transferFrom(address _from, address _to, uint _value) canTransfer(_from, _value) { return super.transferFrom(_from, _to, _value); } - // Default transferable tokens function returns all tokens for a holder (no limit). + /** + * @dev Default transferable tokens function returns all tokens for a holder (no limit). + * @dev Overwriting transferableTokens(address holder, uint64 time) is the way to provide + the specific logic for limiting token transferability for a holder over time. + */ function transferableTokens(address holder, uint64 time) constant public returns (uint256) { return balanceOf(holder); } diff --git a/contracts/token/MintableToken.sol b/contracts/token/MintableToken.sol index cef7ff8d4..62c568a3c 100644 --- a/contracts/token/MintableToken.sol +++ b/contracts/token/MintableToken.sol @@ -7,13 +7,10 @@ import '../ownership/Ownable.sol'; /** - * Mintable token - * - * Simple ERC20 Token example, with mintable token creation - * Issue: - * https://github.com/OpenZeppelin/zeppelin-solidity/issues/120 - * Based on code by TokenMarketNet: - * https://github.com/TokenMarketNet/ico/blob/master/contracts/MintableToken.sol + * @tit;e Mintable token + * @dev: Simple ERC20 Token example, with mintable token creation + @dev Issue: * https://github.com/OpenZeppelin/zeppelin-solidity/issues/120 + * Based on code by TokenMarketNet: https://github.com/TokenMarketNet/ico/blob/master/contracts/MintableToken.sol */ contract MintableToken is StandardToken, Ownable { @@ -23,11 +20,18 @@ contract MintableToken is StandardToken, Ownable { bool public mintingFinished = false; uint public totalSupply = 0; + modifier canMint() { if(mintingFinished) throw; _; } + /** + * @dev Function to mint tokens + * @param _to address The address that will recieve the minted tokens + * @param _amout uint The amount of tokens to mint + * @return A boolean that indicates if the operation was successful + */ function mint(address _to, uint _amount) onlyOwner canMint returns (bool) { totalSupply = totalSupply.add(_amount); balances[_to] = balances[_to].add(_amount); @@ -35,6 +39,10 @@ contract MintableToken is StandardToken, Ownable { return true; } + /** + * @dev Function to spot minting new tokens + * @return True if the operation was successful + */ function finishMinting() onlyOwner returns (bool) { mintingFinished = true; MintFinished(); diff --git a/contracts/token/SimpleToken.sol b/contracts/token/SimpleToken.sol index db9137ff3..9a3fee650 100644 --- a/contracts/token/SimpleToken.sol +++ b/contracts/token/SimpleToken.sol @@ -4,12 +4,12 @@ pragma solidity ^0.4.8; import "./StandardToken.sol"; -/* - * SimpleToken +/** + * @title SimpleToken * - * Very simple ERC20 Token example, where all tokens are pre-assigned - * to the creator. Note they can later distribute these tokens - * as they wish using `transfer` and other `StandardToken` functions. + * @dev Very simple ERC20 Token example, where all tokens are pre-assigned + to the creator. Note they can later distribute these tokens + as they wish using `transfer` and other `StandardToken` functions. */ contract SimpleToken is StandardToken { @@ -17,7 +17,10 @@ contract SimpleToken is StandardToken { string public symbol = "SIM"; uint public decimals = 18; uint public INITIAL_SUPPLY = 10000; - + + /** + * @dev Contructor that gives the msg.sender all of existing tokens. + */ function SimpleToken() { totalSupply = INITIAL_SUPPLY; balances[msg.sender] = INITIAL_SUPPLY; diff --git a/contracts/token/StandardToken.sol b/contracts/token/StandardToken.sol index 865fe1b3c..ec067e6f5 100644 --- a/contracts/token/StandardToken.sol +++ b/contracts/token/StandardToken.sol @@ -6,16 +6,23 @@ import './ERC20.sol'; /** - * Standard ERC20 token + * @title Standard ERC20 token * - * https://github.com/ethereum/EIPs/issues/20 - * Based on code by FirstBlood: - * https://github.com/Firstbloodio/token/blob/master/smart_contract/FirstBloodToken.sol + * @dev Implemantation of the basic standart token. + * @dev https://github.com/ethereum/EIPs/issues/20 + * @dev Based on code by FirstBlood: https://github.com/Firstbloodio/token/blob/master/smart_contract/FirstBloodToken.sol */ contract StandardToken is BasicToken, ERC20 { mapping (address => mapping (address => uint)) allowed; + + /** + * @dev Transfer tokens from one address to another + * @param _from address The address which you want to send tokens from + * @param _to address The address which you want to transfer to + * @param _value uint the amout of tokens to be transfered + */ function transferFrom(address _from, address _to, uint _value) onlyPayloadSize(3 * 32) { var _allowance = allowed[_from][msg.sender]; @@ -28,6 +35,11 @@ contract StandardToken is BasicToken, ERC20 { Transfer(_from, _to, _value); } + /** + * @dev Aprove the passed address to spend the specified amout tokens on the msg.sender behalf. + * @param _spender address The address which will spend the funds. + * @param _value uint the amout of tokens to be spended. + */ function approve(address _spender, uint _value) { // To change the approve amount you first have to reduce the addresses` @@ -40,6 +52,12 @@ contract StandardToken is BasicToken, ERC20 { Approval(msg.sender, _spender, _value); } + /** + * @dev Function to check the amount of tokens than an owner allowed to a spender. + * @param _owner address The address which owns the funds. + * @param _spender address The address which will spend the funds. + * @return A uint specifing the amount of tokens still avaible for the spender. + */ function allowance(address _owner, address _spender) constant returns (uint remaining) { return allowed[_owner][_spender]; } diff --git a/contracts/token/VestedToken.sol b/contracts/token/VestedToken.sol index ded654ebe..e563ba680 100644 --- a/contracts/token/VestedToken.sol +++ b/contracts/token/VestedToken.sol @@ -4,7 +4,13 @@ pragma solidity ^0.4.8; import "./StandardToken.sol"; import "./LimitedTransferToken.sol"; +/** +* @title Vested token +* @dev This tokens can be granted to a specific address after a determined +amount of time. +*/ contract VestedToken is StandardToken, LimitedTransferToken { + struct TokenGrant { address granter; uint256 value; @@ -15,6 +21,14 @@ contract VestedToken is StandardToken, LimitedTransferToken { mapping (address => TokenGrant[]) public grants; + /** + * @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. + */ function grantVestedTokens( address _to, uint256 _value, @@ -39,6 +53,12 @@ contract VestedToken is StandardToken, LimitedTransferToken { transfer(_to, _value); } + + /** + * @dev Revoke the grant of tokens of a specifed address. + * @param _holder address The address which will have its tokens revoked. + * @param _grantId uint The id of the token grant. + */ function revokeTokenGrant(address _holder, uint _grantId) { TokenGrant grant = grants[_holder][_grantId]; @@ -57,10 +77,20 @@ contract VestedToken is StandardToken, LimitedTransferToken { Transfer(_holder, msg.sender, nonVested); } + /** + * @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. + */ function tokenGrantsCount(address _holder) constant returns (uint index) { return grants[_holder].length; } + /** + * @dev + * @param _holder address The address which will have its tokens revoked. + * @param _grantId uint The id of the token grant. + */ 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];