Merge pull request #210 from maurelian/master

Add natspec comments to contracts

contracts/Bounty.sol

@@ -5,10 +5,9 @@ import './payment/PullPayment.sol';
 import './lifecycle/Destructible.sol';
 
 
-/*
- * Bounty
- * 
- * This bounty will pay out to a researcher if they break invariant logic of the contract.
+/**
+ * @title Bounty
+ * @dev This bounty will pay out to a researcher if they break invariant logic of the contract.
  */
 contract Bounty is PullPayment, Destructible {
   bool public claimed;
@@ -16,12 +15,20 @@ contract Bounty is PullPayment, Destructible {
 
   event TargetCreated(address createdAddress);
 
+  /**
+   * @dev Fallback function allowing the contract to recieve funds, if they haven't already been claimed.
+   */
   function() payable {
     if (claimed) {
       throw;
     }
   }
 
+  /**
+   * @dev Create and deploy the target contract (extension of Target contract), and sets the 
+   * msg.sender as a researcher
+   * @return A target contract
+   */
   function createTarget() returns(Target) {
     Target target = Target(deployContract());
     researchers[target] = msg.sender;
@@ -29,8 +36,16 @@ contract Bounty is PullPayment, Destructible {
     return target;
   }
 
+  /**
+   * @dev Internal function to deploy the target contract.
+   * @return A target contract address
+   */
   function deployContract() internal returns(address);
 
+  /**
+   * @dev Sends the contract funds to the researcher that proved the contract is broken.
+   * @param Target contract
+   */
   function claim(Target target) {
     address researcher = researchers[target];
     if (researcher == 0) {
@@ -47,12 +62,17 @@ contract Bounty is PullPayment, Destructible {
 }
 
 
-/*
- * Target
- * 
- * Your main contract should inherit from this class and implement the checkInvariant method. This is a function that should check everything your contract assumes to be true all the time. If this function returns false, it means your contract was broken in some way and is in an inconsistent state. This is what security researchers will try to acomplish when trying to get the bounty.
+/**
+ * @title Target
+ * @dev Your main contract should inherit from this class and implement the checkInvariant method.
  */
 contract Target {
+
+   /**
+    * @dev Checks all values a contract assumes to be true all the time. If this function returns 
+    * false, the contract is broken in some way and is in an inconsistent state. 
+    * In order to win the bounty, security researchers will try to cause this broken state. 
+    * @return True if all invariant values are correct, false otherwise. 
+    */
   function checkInvariant() returns(bool);
 }
-

contracts/DayLimit.sol

 pragma solidity ^0.4.8;
 
-/*
- * DayLimit
- *
- * inheritable "property" contract that enables methods to be protected by placing a linear limit (specifiable)
- * on a particular resource per calendar day. is multiowned to allow the limit to be altered. resource that method
- * uses is specified in the modifier.
+/**
+ * @title DayLimit
+ * @dev Base contract that enables methods to be protected by placing a linear limit (specifiable)
+ * on a particular resource per calendar day. Is multiowned to allow the limit to be altered.
  */
 contract DayLimit {
 
@@ -13,24 +11,35 @@ contract DayLimit {
   uint public spentToday;
   uint public lastDay;
 
-
+  /**
+   * @dev Constructor that sets the passed value as a dailyLimit.
+   * @param _limit Uint to represent the daily limit.
+   */
   function DayLimit(uint _limit) {
     dailyLimit = _limit;
     lastDay = today();
   }
 
-  // sets the daily limit. doesn't alter the amount already spent today
+  /**
+   * @dev sets the daily limit. Does not alter the amount already spent today.
+   * @param _newLimit Uint to represent the new limit.
+   */
   function _setDailyLimit(uint _newLimit) internal {
     dailyLimit = _newLimit;
   }
 
-  // resets the amount already spent today.
+  /**
+   * @dev Resets the amount already spent today.
+   */
   function _resetSpentToday() internal {
     spentToday = 0;
   }
 
-  // checks to see if there is at least `_value` left from the daily limit today. if there is, subtracts it and
-  // returns true. otherwise just returns false.
+  /**
+   * @dev Checks to see if there is enough resource to spend today. If true, the resource may be expended.
+   * @param _value Uint representing the amount of resource to spend.
+   * @return A boolean that is True if the resource was spended and false otherwise.
+   */
   function underLimit(uint _value) internal returns (bool) {
     // reset the spend limit if we're on a different day to last time.
     if (today() > lastDay) {
@@ -46,13 +55,17 @@ contract DayLimit {
     return false;
   }
 
-  // determines today's index.
+  /**
+   * @dev Private function to determine today's index
+   * @return Uint of today's index.
+   */
   function today() private constant returns (uint) {
     return now / 1 days;
   }
 
-
-  // simple modifier for daily limit.
+  /**
+   * @dev Simple modifier for daily limit.
+   */
   modifier limitedDaily(uint _value) {
     if (!underLimit(_value)) {
       throw;

contracts/LimitBalance.sol

@@ -2,26 +2,32 @@ pragma solidity ^0.4.8;
 
 
 /**
- * LimitBalance
- * Simple contract to limit the balance of child contract.
- * Note this doesn't prevent other contracts to send funds 
- * by using selfdestruct(address);
- * See: https://github.com/ConsenSys/smart-contract-best-practices#remember-that-ether-can-be-forcibly-sent-to-an-account
+ * @title LimitBalance
+ * @dev Simple contract to limit the balance of child contract.
+ * @dev Note this doesn't prevent other contracts to send funds by using selfdestruct(address);
+ * @dev See: https://github.com/ConsenSys/smart-contract-best-practices#remember-that-ether-can-be-forcibly-sent-to-an-account
  */
 contract LimitBalance {
 
   uint public limit;
 
+  /**
+   * @dev Constructor that sets the passed value as a limit. 
+   * @param _limit Uint to represent the limit.
+   */
   function LimitBalance(uint _limit) {
     limit = _limit;
   }
 
-  modifier limitedPayable() { 
+  /**
+   * @dev Checks if limit was reached. Case true, it throws.
+   */
+  modifier limitedPayable() {
     if (this.balance > limit) {
       throw;
     }
     _;
-    
+
   }
 
 }

contracts/MultisigWallet.sol

@@ -6,11 +6,11 @@ import "./ownership/Shareable.sol";
 import "./DayLimit.sol";
 
 
-/*
+/**
  * MultisigWallet
- * usage:
- * bytes32 h = Wallet(w).from(oneOwner).execute(to, value, data);
- * Wallet(w).from(anotherOwner).confirm(h);
+ * Usage:
+ *     bytes32 h = Wallet(w).from(oneOwner).execute(to, value, data);
+ *     Wallet(w).from(anotherOwner).confirm(h);
  */
 contract MultisigWallet is Multisig, Shareable, DayLimit {
 
@@ -20,26 +20,41 @@ contract MultisigWallet is Multisig, Shareable, DayLimit {
     bytes data;
   }
 
+  /**
+   * Constructor, sets the owners addresses, number of approvals required, and daily spending limit
+   * @param _owners A list of owners.
+   * @param _required The amount required for a transaction to be approved.
+   */
   function MultisigWallet(address[] _owners, uint _required, uint _daylimit)       
     Shareable(_owners, _required)        
     DayLimit(_daylimit) { }
 
-  // destroys the contract sending everything to `_to`.
+  /** 
+   * @dev destroys the contract sending everything to `_to`. 
+   */
   function destroy(address _to) onlymanyowners(keccak256(msg.data)) external {
     selfdestruct(_to);
   }
 
-  // gets called when no other function matches
+  /** 
+   * @dev Fallback function, receives value and emits a deposit event. 
+   */
   function() payable {
     // just being sent some cash?
     if (msg.value > 0)
       Deposit(msg.sender, msg.value);
   }
 
-  // Outside-visible transact entry point. Executes transaction immediately if below daily spend limit.
-  // If not, goes into multisig process. We provide a hash on return to allow the sender to provide
-  // shortcuts for the other confirmations (allowing them to avoid replicating the _to, _value
-  // and _data arguments). They still get the option of using them if they want, anyways.
+  /**
+   * @dev Outside-visible transaction entry point. Executes transaction immediately if below daily 
+   * spending limit. If not, goes into multisig process. We provide a hash on return to allow the 
+   * sender to provide shortcuts for the other confirmations (allowing them to avoid replicating 
+   * the _to, _value, and _data arguments). They still get the option of using them if they want, 
+   * anyways.
+   * @param _to The receiver address
+   * @param _value The value to send
+   * @param _data The data part of the transaction
+   */
   function execute(address _to, uint _value, bytes _data) external onlyOwner returns (bytes32 _r) {
     // first, take the opportunity to check that we're under the daily limit.
     if (underLimit(_value)) {
@@ -60,8 +75,11 @@ contract MultisigWallet is Multisig, Shareable, DayLimit {
     }
   }
 
-  // confirm a transaction through just the hash. we use the previous transactions map, txs, in order
-  // to determine the body of the transaction from the hash provided.
+  /**
+   * @dev Confirm a transaction by providing just the hash. We use the previous transactions map, 
+   * txs, in order to determine the body of the transaction from the hash provided.
+   * @param _h The transaction hash to approve.
+   */
   function confirm(bytes32 _h) onlymanyowners(_h) returns (bool) {
     if (txs[_h].to != 0) {
       if (!txs[_h].to.call.value(txs[_h].value)(txs[_h].data)) {
@@ -73,17 +91,27 @@ contract MultisigWallet is Multisig, Shareable, DayLimit {
     }
   }
 
+  /** 
+   * @dev Updates the daily limit value. 
+   * @param _newLimit 
+   */
   function setDailyLimit(uint _newLimit) onlymanyowners(keccak256(msg.data)) external {
     _setDailyLimit(_newLimit);
   }
 
+  /** 
+   * @dev Resets the value spent to enable more spending
+   * @param _newLimit 
+   */
   function resetSpentToday() onlymanyowners(keccak256(msg.data)) external {
     _resetSpentToday();
   }
 
 
   // INTERNAL METHODS
-
+  /** 
+   * @dev Clears the list of transactions pending approval.
+   */
   function clearPending() internal {
     uint length = pendingsIndex.length;
     for (uint i = 0; i < length; ++i) {

contracts/ReentrancyGuard.sol

 pragma solidity ^0.4.8;
 
-/// @title Helps contracts guard agains rentrancy attacks.
-/// @author Remco Bloemen <remco@2π.com>
-/// @notice If you mark a function `nonReentrant`, you should also
-/// mark it `external`.
+/**
+ * @title Helps contracts guard agains rentrancy attacks.
+ * @author Remco Bloemen <remco@2π.com>
+ * @notice If you mark a function `nonReentrant`, you should also
+ * mark it `external`.
+ */
 contract ReentrancyGuard {
 
-  /// @dev We use a single lock for the whole contract.
+  /**
+   * @dev We use a single lock for the whole contract. 
+   */
   bool private rentrancy_lock = false;
 
-  /// Prevent contract from calling itself, directly or indirectly.
-  /// @notice If you mark a function `nonReentrant`, you should also
-  /// mark it `external`. Calling one nonReentrant function from
-  /// another is not supported. Instead, you can implement a
-  /// `private` function doing the actual work, and a `external`
-  /// wrapper marked as `nonReentrant`.
+  /**
+   * @dev Prevents a contract from calling itself, directly or indirectly.
+   * @notice If you mark a function `nonReentrant`, you should also
+   * mark it `external`. Calling one nonReentrant function from
+   * another is not supported. Instead, you can implement a
+   * `private` function doing the actual work, and a `external`
+   * wrapper marked as `nonReentrant`.
+   */
   modifier nonReentrant() {
     if(rentrancy_lock == false) {
       rentrancy_lock = true;

contracts/lifecycle/Destructible.sol

@@ -4,11 +4,15 @@ pragma solidity ^0.4.8;
 import "../ownership/Ownable.sol";
 
 
-/*
- * Destructible
- * Base contract that can be destroyed by owner. All funds in contract will be sent to the owner.
+/**
+ * @title Destructible
+ * @dev Base contract that can be destroyed by owner. All funds in contract will be sent to the owner.
  */
 contract Destructible is Ownable {
+
+  /**
+   * @dev Transfers the current balance to the owner and terminates the contract. 
+   */
   function destroy() onlyOwner {
     selfdestruct(owner);
   }

contracts/lifecycle/Migrations.sol

@@ -3,8 +3,10 @@ pragma solidity ^0.4.8;
 
 import '../ownership/Ownable.sol';
 
-
-// This is a truffle contract, needed for truffle integration, not meant for use by Zeppelin users. 
+/**
+ * @title Migrations
+ * @dev This is a truffle contract, needed for truffle integration, not meant for use by Zeppelin users.
+ */
 contract Migrations is Ownable {
   uint public lastCompletedMigration;
 

contracts/lifecycle/Pausable.sol

@@ -4,10 +4,9 @@ pragma solidity ^0.4.8;
 import "../ownership/Ownable.sol";
 
 
-/*
- * Pausable
- * Abstract contract that allows children to implement a
- * pause mechanism.
+/**
+ * @title Pausable
+ * @dev Base contract which allows children to implement an emergency stop mechanism.
  */
 contract Pausable is Ownable {
   event Pause();
@@ -15,24 +14,35 @@ contract Pausable is Ownable {
 
   bool public paused = false;
 
+
+  /**
+   * @dev modifier to allow actions only when the contract IS paused
+   */
   modifier whenNotPaused() {
     if (paused) throw;
     _;
   }
 
+  /**
+   * @dev modifier to allow actions only when the contract IS NOT paused
+   */
   modifier whenPaused {
     if (!paused) throw;
     _;
   }
 
-  // called by the owner to pause, triggers stopped state
+  /**
+   * @dev called by the owner to pause, triggers stopped state
+   */
   function pause() onlyOwner whenNotPaused returns (bool) {
     paused = true;
     Pause();
     return true;
   }
 
-  // called by the owner to unpause, returns to normal state
+  /**
+   * @dev called by the owner to unpause, returns to normal state
+   */
   function unpause() onlyOwner whenPaused returns (bool) {
     paused = false;
     Unpause();

contracts/lifecycle/TokenDestructible.sol

@@ -4,17 +4,21 @@ pragma solidity ^0.4.8;
 import "../ownership/Ownable.sol";
 import "../token/ERC20Basic.sol";
 
-/// @title TokenDestructible:
-/// @author Remco Bloemen <remco@2π.com>
-///.Base contract that can be destroyed by owner. All funds in contract including
-/// listed tokens will be sent to the owner
+/** 
+ * @title TokenDestructible:
+ * @author Remco Bloemen <remco@2π.com>
+ * @dev Base contract that can be destroyed by owner. All funds in contract including
+ * listed tokens will be sent to the owner.
+ */
 contract TokenDestructible is Ownable {
 
-  /// @notice Terminate contract and refund to owner
-  /// @param  tokens List of addresses of ERC20 or ERC20Basic token contracts to
-  //          refund
-  /// @notice The called token contracts could try to re-enter this contract.
-  //          Only supply token contracts you
+  /** 
+   * @notice Terminate contract and refund to owner
+   * @param tokens List of addresses of ERC20 or ERC20Basic token contracts to
+   refund.
+   * @notice The called token contracts could try to re-enter this contract. Only
+   supply token contracts you trust.
+   */
   function destroy(address[] tokens) onlyOwner {
 
     // Transfer tokens to owner

contracts/ownership/Claimable.sol

@@ -4,14 +4,17 @@ pragma solidity ^0.4.8;
 import './Ownable.sol';
 
 
-/*
- * Claimable
- *
- * Extension for the Ownable contract, where the ownership needs to be claimed. This allows the new owner to accept the transfer.
+/**
+ * @title Claimable
+ * @dev Extension for the Ownable contract, where the ownership needs to be claimed. 
+ * This allows the new owner to accept the transfer.
  */
 contract Claimable is Ownable {
   address public pendingOwner;
 
+  /**
+   * @dev Modifier throws if called by any account other than the pendingOwner. 
+   */
   modifier onlyPendingOwner() {
     if (msg.sender != pendingOwner) {
       throw;
@@ -19,13 +22,19 @@ contract Claimable is Ownable {
     _;
   }
 
+  /**
+   * @dev Allows the current owner to set the pendingOwner address. 
+   * @param newOwner The address to transfer ownership to. 
+   */
   function transferOwnership(address newOwner) onlyOwner {
     pendingOwner = newOwner;
   }
 
+  /**
+   * @dev Allows the pendingOwner address to finalize the transfer.
+   */
   function claimOwnership() onlyPendingOwner {
     owner = pendingOwner;
     pendingOwner = 0x0;
   }
-
 }

contracts/ownership/Contactable.sol

 pragma solidity ^0.4.8;
 
 import './Ownable.sol';
-/*
- * Contactable token
- * Basic version of a contactable contract
+
+/**
+ * @title Contactable token
+ * @dev Basic version of a contactable contract, allowing the owner to provide a string with their 
+ * contact information.
  */
 contract Contactable is Ownable{
 
-     string public contactInformation;
+    string public contactInformation;
 
-     function setContactInformation(string info) onlyOwner{
+    /**
+     * @dev Allows the owner to set a string with their contact information.
+     * @param info The contact information to attach to the contract.
+     */
+    function setContactInformation(string info) onlyOwner{
          contactInformation = info;
      }
-
 }

contracts/ownership/DelayedClaimable.sol

@@ -4,15 +4,22 @@ pragma solidity ^0.4.8;
 import './Claimable.sol';
 
 
-/*
- * DelayedClaimable
- * Extension for the Claimable contract, where the ownership needs to be claimed before/after certain block number
+/**
+ * @title DelayedClaimable
+ * @dev Extension for the Claimable contract, where the ownership needs to be claimed before/after
+ * a certain block number.
  */
 contract DelayedClaimable is Claimable {
 
   uint public end;
   uint public start;
 
+  /**
+   * @dev Used to specify the time period during which a pending 
+   * owner can claim ownership. 
+   * @params _start The earliest time ownership can be claimed.
+   * @params _end The latest time ownership can be claimed. 
+   */
   function setLimits(uint _start, uint _end) onlyOwner {
     if (_start > _end)
         throw;
@@ -20,6 +27,11 @@ contract DelayedClaimable is Claimable {
     start = _start;
   }
 
+
+  /**
+   * @dev Allows the pendingOwner address to finalize the transfer, as long as it is called within 
+   * the specified start and end time. 
+   */
   function claimOwnership() onlyPendingOwner {
     if ((block.number > end) || (block.number < start))
         throw;

contracts/ownership/HasNoContracts.sol

@@ -2,15 +2,18 @@ pragma solidity ^0.4.8;
 
 import "./Ownable.sol";
 
-/// @title Contracts that should not own Contracts
-/// @author Remco Bloemen <remco@2π.com>
-///
-/// Should contracts (anything Ownable) end up being owned by
-/// this contract, it allows the owner of this contract to
-/// reclaim ownership of the contracts.
+/** 
+ * @title Contracts that should not own Contracts
+ * @author Remco Bloemen <remco@2π.com>
+ * @dev Should contracts (anything Ownable) end up being owned by this contract, it allows the owner
+ * of this contract to reclaim ownership of the contracts.
+ */
 contract HasNoContracts is Ownable {
 
-  /// Reclaim ownership of Ownable contracts
+  /**
+   * @dev Reclaim ownership of Ownable contracts
+   * @param contractAddr The address of the Ownable to be reclaimed.
+   */
   function reclaimContract(address contractAddr) external onlyOwner {
     Ownable contractInst = Ownable(contractAddr);
     contractInst.transferOwnership(owner);

contracts/ownership/HasNoEther.sol

@@ -2,38 +2,40 @@ pragma solidity ^0.4.8;
 
 import "./Ownable.sol";
 
-/// @title Contracts that should not own Ether
-/// @author Remco Bloemen <remco@2π.com>
-///
-/// This tries to block incoming ether to prevent accidental
-/// loss of Ether. Should Ether end up in the contrat, it will
-/// allow the owner to reclaim this ether.
-///
-/// @notice Ether can still be send to this contract by:
-///  * calling functions labeled `payable`
-///  * `selfdestruct(contract_address)`
-///  * mining directly to the contract address
+/** 
+ * @title Contracts that should not own Ether
+ * @author Remco Bloemen <remco@2π.com>
+ * @dev This tries to block incoming ether to prevent accidental loss of Ether. Should Ether end up
+ * in the contract, it will allow the owner to reclaim this ether.
+ * @notice Ether can still be send to this contract by:
+ * calling functions labeled `payable`
+ * `selfdestruct(contract_address)`
+ * mining directly to the contract address
+*/
 contract HasNoEther is Ownable {
 
-  /// Constructor that rejects incoming Ether
-  /// @dev The flag `payable` is added so we can access `msg.value`
-  ///      without compiler warning. If we leave out payable, then
-  ///      Solidity will allow inheriting contracts to implement a
-  ///      payable constructor. By doing it this way we prevent a
-  ///      payable constructor from working.
-  ///      Alternatively we could use assembly to access msg.value.
+  /**
+  * @dev Constructor that rejects incoming Ether
+  * @dev The `payable` flag is added so we can access `msg.value` without compiler warning. If we 
+  * leave out payable, then Solidity will allow inheriting contracts to implement a payable 
+  * constructor. By doing it this way we prevent a payable constructor from working. Alternatively 
+  * we could use assembly to access msg.value.
+  */
   function HasNoEther() payable {
     if(msg.value > 0) {
       throw;
     }
   }
 
-  /// Disallow direct send by settings a default function without `payable`
+  /**
+   * @dev Disallows direct send by settings a default function without the `payable` flag.
+   */
   function() external {
   }
 
-  /// Transfer all Ether owned by the contract to the owner
-  /// @dev What if owner is itself a contract marked HasNoEther?
+  /**
+   * @dev Transfer all Ether held by the contract to the owner.
+   */
   function reclaimEther() external onlyOwner {
     if(!owner.send(this.balance)) {
       throw;

contracts/ownership/HasNoTokens.sol

@@ -3,21 +3,29 @@ pragma solidity ^0.4.8;
 import "./Ownable.sol";
 import "../token/ERC20Basic.sol";
 
-/// @title Contracts that should not own Tokens
-/// @author Remco Bloemen <remco@2π.com>
-///
-/// This blocks incoming ERC23 tokens to prevent accidental
-/// loss of tokens. Should tokens (any ERC20Basic compatible)
-/// end up in the contract, it allows the owner to reclaim
-/// the tokens.
+/** 
+ * @title Contracts that should not own Tokens
+ * @author Remco Bloemen <remco@2π.com>
+ * @dev This blocks incoming ERC23 tokens to prevent accidental loss of tokens.
+ * Should tokens (any ERC20Basic compatible) end up in the contract, it allows the
+ * owner to reclaim the tokens.
+ */
 contract HasNoTokens is Ownable {
 
-  /// Reject all ERC23 compatible tokens
+ /** 
+  * @dev Reject all ERC23 compatible tokens
+  * @param from_ address The address that is transferring the tokens
+  * @param value_ Uint the amount of the specified token
+  * @param data_ Bytes The data passed from the caller.
+  */
   function tokenFallback(address from_, uint value_, bytes data_) external {
     throw;
   }
 
-  /// Reclaim all ERC20Basic compatible tokens
+  /**
+   * @dev Reclaim all ERC20Basic compatible tokens
+   * @param tokenAddr address The address of the token contract
+   */
   function reclaimToken(address tokenAddr) external onlyOwner {
     ERC20Basic tokenInst = ERC20Basic(tokenAddr);
     uint256 balance = tokenInst.balanceOf(this);

contracts/ownership/Multisig.sol

 pragma solidity ^0.4.8;
 
 
-/*
- * Multisig
- * Interface contract for multisig proxy contracts; see below for docs.
+/**
+ * @title Multisig
+ * @dev Interface contract for multisig proxy contracts; see below for docs.
  */
 contract Multisig {
   // EVENTS
@@ -26,4 +26,3 @@ contract Multisig {
   function execute(address _to, uint _value, bytes _data) external returns (bytes32);
   function confirm(bytes32 _h) returns (bool);
 }
-

contracts/ownership/NoOwner.sol

@@ -4,11 +4,11 @@ import "./HasNoEther.sol";
 import "./HasNoTokens.sol";
 import "./HasNoContracts.sol";
 
-/// @title Base contract for contracts that should not own things.
-/// @author Remco Bloemen <remco@2π.com>
-///
-/// Solves a class of errors where a contract accidentally
-/// becomes owner of Ether, Tokens or Owned contracts. See
-/// respective base contracts for details.
+/** 
+ * @title Base contract for contracts that should not own things.
+ * @author Remco Bloemen <remco@2π.com>
+ * @dev Solves a class of errors where a contract accidentally becomes owner of Ether, Tokens or 
+ * Owned contracts. See respective base contracts for details.
+ */
 contract NoOwner is HasNoEther, HasNoTokens, HasNoContracts {
 }

contracts/ownership/Ownable.sol

 pragma solidity ^0.4.8;
 
 
-/*
- * Ownable
- *
- * Base contract with an owner.
- * Provides onlyOwner modifier, which prevents function from running if it is called by anyone other than the owner.
+/**
+ * @title Ownable
+ * @dev The Ownable contract has an owner address, and provides basic authorization control 
+ * functions, this simplifies the implementation of "user permissions". 
  */
 contract Ownable {
   address public owner;
 
+
+  /** 
+   * @dev The Ownable constructor sets the original `owner` of the contract to the sender
+   * account.
+   */
   function Ownable() {
     owner = msg.sender;
   }
 
+
+  /**
+   * @dev Throws if called by any account other than the owner. 
+   */
   modifier onlyOwner() {
     if (msg.sender != owner) {
       throw;
@@ -21,6 +29,11 @@ contract Ownable {
     _;
   }
 
+
+  /**
+   * @dev Allows the current owner to transfer control of the contract to a newOwner.
+   * @param newOwner The address to transfer ownership to. 
+   */
   function transferOwnership(address newOwner) onlyOwner {
     if (newOwner != address(0)) {
       owner = newOwner;

contracts/ownership/Shareable.sol

 pragma solidity ^0.4.8;
 
 
-/*
- * Shareable
- *
- * Based on https://github.com/ethereum/dapp-bin/blob/master/wallet/wallet.sol
- *
- * inheritable "property" contract that enables methods to be protected by requiring the acquiescence of either a single, or, crucially, each of a number of, designated owners.
- *
- * usage:
- * use modifiers onlyowner (just own owned) or onlymanyowners(hash), whereby the same hash must be provided by some number (specified in constructor) of the set of owners (specified in the constructor) before the interior is executed.
+/**
+ * @title Shareable
+ * @dev inheritable "property" contract that enables methods to be protected by requiring the 
+ * acquiescence of either a single, or, crucially, each of a number of, designated owners.
+ * @dev Usage: use modifiers onlyowner (just own owned) or onlymanyowners(hash), whereby the same hash must be provided by some number (specified in constructor) of the set of owners (specified in the constructor) before the interior is executed.
  */
 contract Shareable {
+
   // struct for the status of a pending operation.
   struct PendingState {
     uint yetNeeded;
@@ -44,18 +41,25 @@ contract Shareable {
     }
     _;
   }
-
-  // multi-sig function modifier: the operation must have an intrinsic hash in order
-  // that later attempts can be realised as the same underlying operation and
-  // thus count as confirmations.
+  
+  /** 
+   * @dev Modifier for multisig functions. 
+   * @param _operation The operation must have an intrinsic hash in order that later attempts can be
+   * realised as the same underlying operation and thus count as confirmations.
+   */
   modifier onlymanyowners(bytes32 _operation) {
     if (confirmAndCheck(_operation)) {
       _;
     }
   }
 
-  // constructor is given number of sigs required to do protected "onlymanyowners" transactions
-  // as well as the selection of addresses capable of confirming them.
+  /** 
+   * @dev Constructor is given the number of sigs required to do protected "onlymanyowners" 
+   * transactions as well as the selection of addresses capable of confirming them.
+   * @param _owners A list of owners.
+   * @param _required The amount required for a transaction to be approved.
+   * @param _limit Uint to represent the daily limit.
+   */
   function Shareable(address[] _owners, uint _required) {
     owners[1] = msg.sender;
     ownerIndex[msg.sender] = 1;
@@ -69,7 +73,10 @@ contract Shareable {
     }
   }
 
-  // Revokes a prior confirmation of the given operation
+  /**
+   * @dev Revokes a prior confirmation of the given operation.
+   * @param _operation A string identifying the operation.
+   */
   function revoke(bytes32 _operation) external {
     uint index = ownerIndex[msg.sender];
     // make sure they're an owner
@@ -85,15 +92,30 @@ contract Shareable {
     }
   }
 
-  // Gets an owner by 0-indexed position (using numOwners as the count)
+  /**
+   * @dev Gets an owner by 0-indexed position (using numOwners as the count)
+   * @param ownerIndex Uint The index of the owner
+   * @return The address of the owner
+   */
   function getOwner(uint ownerIndex) external constant returns (address) {
     return address(owners[ownerIndex + 1]);
   }
 
+  /**
+   * @dev Checks if given address is an owner.
+   * @param _addr address The address which you want to check.
+   * @return True if the address is an owner and fase otherwise.
+   */
   function isOwner(address _addr) constant returns (bool) {
     return ownerIndex[_addr] > 0;
   }
 
+  /**
+   * @dev Function to check is specific owner has already confirme the operation.
+   * @param _operation The operation identifier.
+   * @param _owner The owner address.
+   * @return True if the owner has confirmed and false otherwise.
+   */
   function hasConfirmed(bytes32 _operation, address _owner) constant returns (bool) {
     var pending = pendings[_operation];
     uint index = ownerIndex[_owner];
@@ -108,7 +130,11 @@ contract Shareable {
     return !(pending.ownersDone & ownerIndexBit == 0);
   }
 
-  // returns true when operation can be executed
+  /**
+   * @dev Confirm and operation and checks if it's already executable.
+   * @param _operation The operation identifier.
+   * @return Returns true when operation can be executed.
+   */
   function confirmAndCheck(bytes32 _operation) internal returns (bool) {
     // determine what index the present sender is:
     uint index = ownerIndex[msg.sender];
@@ -147,6 +173,10 @@ contract Shareable {
     return false;
   }
 
+
+  /**
+   * @dev Clear the pending list.
+   */
   function clearPending() internal {
     uint length = pendingsIndex.length;
     for (uint i = 0; i < length; ++i) {

contracts/payment/PullPayment.sol

@@ -4,10 +4,10 @@ pragma solidity ^0.4.8;
 import '../SafeMath.sol';
 
 
-/*
- * PullPayment
- * Base contract supporting async send for pull payments.
- * Inherit from this contract and use asyncSend instead of send.
+/**
+ * @title PullPayment
+ * @dev Base contract supporting async send for pull payments. Inherit from this
+ * contract and use asyncSend instead of send.
  */
 contract PullPayment {
   using SafeMath for uint;
@@ -15,13 +15,19 @@ contract PullPayment {
   mapping(address => uint) public payments;
   uint public totalPayments;
 
-  // store sent amount as credit to be pulled, called by payer
+  /**
+  * @dev Called by the payer to store the sent amount as credit to be pulled.
+  * @param dest The destination address of the funds.
+  * @param amount The amount to transfer.
+  */
   function asyncSend(address dest, uint amount) internal {
     payments[dest] = payments[dest].add(amount);
     totalPayments = totalPayments.add(amount);
   }
 
-  // withdraw accumulated balance, called by payee
+  /**
+  * @dev withdraw accumulated balance, called by payee.
+  */
   function withdrawPayments() {
     address payee = msg.sender;
     uint payment = payments[payee];

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 The address to transfer to.
+  * @param _value The amount to be transferred.
+  */
   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 Gets the balance of the specified address.
+  * @param _owner The address to query the the balance of. 
+  * @return An uint representing the amount owned by the passed address.
+  */
   function balanceOf(address _owner) constant returns (uint balance) {
     return balances[_owner];
   }
-  
+
 }

contracts/token/CrowdsaleToken.sol

@@ -4,29 +4,37 @@ pragma solidity ^0.4.8;
 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 Fallback function which receives ether and sends the appropriate number of tokens to the 
+   * msg.sender.
+   */
   function () payable {
     createTokens(msg.sender);
   }
-  
+
+  /**
+   * @dev Creates tokens and send to the specified address.
+   * @param recipient 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;
   }

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);

contracts/token/ERC20Basic.sol

 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;

contracts/token/LimitedTransferToken.sol

@@ -2,47 +2,55 @@ pragma solidity ^0.4.8;
 
 import "./ERC20.sol";
 
-/*
-
-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));
-}
-
-A working example is VestedToken.sol:
-https://github.com/OpenZeppelin/zeppelin-solidity/blob/master/contracts/token/VestedToken.sol
-
-*/
+/**
+ * @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. 
+ * 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));
+ *     }
+ * A working example is VestedToken.sol:
+ * https://github.com/OpenZeppelin/zeppelin-solidity/blob/master/contracts/token/VestedToken.sol
+ */
 
 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 The address that will recieve the tokens.
+   * @param _value The amount of tokens to be transferred.
+   */
   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 The address that will send the tokens.
+  * @param _to The address that will recieve the tokens.
+  * @param _value The amount of tokens to be transferred.
+  */
   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);
   }

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
+ * @title 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 The address that will recieve the minted tokens.
+   * @param _amount 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 stop minting new tokens.
+   * @return True if the operation was successful.
+   */
   function finishMinting() onlyOwner returns (bool) {
     mintingFinished = true;
     MintFinished();

contracts/token/SimpleToken.sol

@@ -4,12 +4,11 @@ pragma solidity ^0.4.8;
 import "./StandardToken.sol";
 
 
-/*
- * 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.
+/**
+ * @title SimpleToken
+ * @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 +16,10 @@ contract SimpleToken is StandardToken {
   string public symbol = "SIM";
   uint public decimals = 18;
   uint public INITIAL_SUPPLY = 10000;
-  
+
+  /**
+   * @dev Contructor that gives msg.sender all of existing tokens. 
+   */
   function SimpleToken() {
     totalSupply = INITIAL_SUPPLY;
     balances[msg.sender] = INITIAL_SUPPLY;

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 amount of tokens on beahlf of msg.sender.
+   * @param _spender The address which will spend the funds.
+   * @param _value The amount of tokens to be spent.
+   */
   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];
   }

contracts/token/VestedToken.sol

@@ -4,6 +4,10 @@ pragma solidity ^0.4.8;
 import "./StandardToken.sol";
 import "./LimitedTransferToken.sol";
 
+/**
+ * @title Vested token
+ * @dev Tokens that can be vested for a group of addresses.
+ */
 contract VestedToken is StandardToken, LimitedTransferToken {
   struct TokenGrant {
     address granter;
@@ -15,6 +19,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 uint64 Time of the beginning of the grant.
+   * @param _cliff uint64 Time of the cliff period.
+   * @param _vesting uint64 The vesting period.
+   */
   function grantVestedTokens(
     address _to,
     uint256 _value,
@@ -39,6 +51,12 @@ contract VestedToken is StandardToken, LimitedTransferToken {
     transfer(_to, _value);
   }
 
+
+  /**
+   * @dev Revoke the grant of tokens of a specifed address.
+   * @param _holder The address which will have its tokens revoked.
+   * @param _grantId The id of the token grant.
+   */
   function revokeTokenGrant(address _holder, uint _grantId) {
     TokenGrant grant = grants[_holder][_grantId];
 
@@ -57,10 +75,22 @@ contract VestedToken is StandardToken, LimitedTransferToken {
     Transfer(_holder, msg.sender, nonVested);
   }
 
+  /**
+   * @dev Check the amount of grants that an address has.
+   * @param _holder The holder of the grants.
+   * @return A uint representing the total amount of grants.
+   */
   function tokenGrantsCount(address _holder) constant returns (uint index) {
     return grants[_holder].length;
   }
 
+  /**
+   * @dev Get all information about a specifc grant.
+   * @param _holder The address which will have its tokens revoked.
+   * @param _grantId 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];
 
@@ -73,6 +103,12 @@ contract VestedToken is StandardToken, LimitedTransferToken {
     vested = vestedTokens(grant, uint64(now));
   }
 
+  /**
+   * @dev Get the amount of vested tokens at a specific time.
+   * @param grant TokenGrant The grant to be checked.
+   * @param time The time to be checked
+   * @return An uint representing the amount of vested tokens of a specific grant at a specific time.
+   */
   function vestedTokens(TokenGrant grant, uint64 time) private constant returns (uint256) {
     return calculateVestedTokens(
       grant.value,
@@ -83,6 +119,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 The cliff period.
+   * @param _vesting uint64 The vesting period.
+   * @return An uint representing the amount of vested tokensof a specif grant.
+   */
   function calculateVestedTokens(
     uint256 tokens,
     uint256 time,
@@ -106,10 +151,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;
@@ -118,6 +175,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++) {