From 1547922b6115d185d680a84afc5022675d97384a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Gabriel=20Carvalho?= Date: Mon, 1 May 2017 13:48:20 -0300 Subject: [PATCH] Added natspec to the remaining ownership contracts and payment contracts --- contracts/ownership/HasNoContracts.sol | 16 ++++---- contracts/ownership/HasNoEther.sol | 48 +++++++++++++----------- contracts/ownership/HasNoTokens.sol | 24 +++++++----- contracts/ownership/NoOwner.sol | 10 ++--- contracts/ownership/Shareable.sol | 52 +++++++++++++++++++------- contracts/payment/PullPayment.sol | 18 ++++++--- 6 files changed, 106 insertions(+), 62 deletions(-) diff --git a/contracts/ownership/HasNoContracts.sol b/contracts/ownership/HasNoContracts.sol index 842638dc2..3d3dee2bb 100644 --- a/contracts/ownership/HasNoContracts.sol +++ b/contracts/ownership/HasNoContracts.sol @@ -2,15 +2,17 @@ pragma solidity ^0.4.8; import "./Ownable.sol"; -/// @title Contracts that should not own Contracts -/// @author Remco Bloemen -/// -/// 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 +* @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 address The Ownable contract address wished to + be reclaimed + */ function reclaimContract(address contractAddr) external onlyOwner { Ownable contractInst = Ownable(contractAddr); contractInst.transferOwnership(owner); diff --git a/contracts/ownership/HasNoEther.sol b/contracts/ownership/HasNoEther.sol index 765983791..d18745d0d 100644 --- a/contracts/ownership/HasNoEther.sol +++ b/contracts/ownership/HasNoEther.sol @@ -2,38 +2,44 @@ pragma solidity ^0.4.8; import "./Ownable.sol"; -/// @title Contracts that should not own Ether -/// @author Remco Bloemen -/// -/// 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 + +* @dev 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 +*/ 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 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. + */ function HasNoEther() payable { if(msg.value > 0) { throw; } } - /// Disallow direct send by settings a default function without `payable` + /** + * @dev Disallow direct send by settings a default function without `payable` + */ 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 owned by the contract to the owner + * @dev What if owner is itself a contract marked HasNoEther? + */ function reclaimEther() external onlyOwner { if(!owner.send(this.balance)) { throw; diff --git a/contracts/ownership/HasNoTokens.sol b/contracts/ownership/HasNoTokens.sol index 9b376930b..533d57db8 100644 --- a/contracts/ownership/HasNoTokens.sol +++ b/contracts/ownership/HasNoTokens.sol @@ -3,21 +3,27 @@ pragma solidity ^0.4.8; import "./Ownable.sol"; import "../token/ERC20Basic.sol"; -/// @title Contracts that should not own Tokens -/// @author Remco Bloemen -/// -/// 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 +* @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 transfering 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); diff --git a/contracts/ownership/NoOwner.sol b/contracts/ownership/NoOwner.sol index f7a567e56..ff06b7ae1 100644 --- a/contracts/ownership/NoOwner.sol +++ b/contracts/ownership/NoOwner.sol @@ -4,11 +4,9 @@ import "./HasNoEther.sol"; import "./HasNoTokens.sol"; import "./HasNoContracts.sol"; -/// @title Base contract for contracts that should not own things. -/// @author Remco Bloemen -/// -/// 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 +* @devSolves 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 { } diff --git a/contracts/ownership/Shareable.sol b/contracts/ownership/Shareable.sol index 8b8477d41..e9d7f4671 100644 --- a/contracts/ownership/Shareable.sol +++ b/contracts/ownership/Shareable.sol @@ -1,17 +1,14 @@ pragma solidity ^0.4.8; -/* - * Shareable +/** + * @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. * - * 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. + * @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; @@ -54,8 +51,11 @@ contract Shareable { } } - // 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 number of sigs required to do protected "onlymanyowners" transactions + * as well as the selection of addresses capable of confirming them. + * @param _owners address[] A list of owners + * @param _required Uint The amout required for a transaction to be approved. + */ function Shareable(address[] _owners, uint _required) { owners[1] = msg.sender; ownerIndex[msg.sender] = 1; @@ -69,7 +69,10 @@ contract Shareable { } } - // Revokes a prior confirmation of the given operation + /** + * @dev Revokes a prior confirmation of the given operation + * @param _operation bytes32 A string the identfies the operation. + */ function revoke(bytes32 _operation) external { uint index = ownerIndex[msg.sender]; // make sure they're an owner @@ -85,15 +88,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 bytes32 The operation identifier + * @param _owner address The owner address + * @return True if the owner has confirmed and flase otherwise + */ function hasConfirmed(bytes32 _operation, address _owner) constant returns (bool) { var pending = pendings[_operation]; uint index = ownerIndex[_owner]; @@ -108,7 +126,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 bytes32 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 +169,10 @@ contract Shareable { return false; } + + /** + * @dev Clear the pedings list. + */ function clearPending() internal { uint length = pendingsIndex.length; for (uint i = 0; i < length; ++i) { diff --git a/contracts/payment/PullPayment.sol b/contracts/payment/PullPayment.sol index 69e30c1d8..9efc8da96 100644 --- a/contracts/payment/PullPayment.sol +++ b/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 store sent amount as credit to be pulled, called by payer + * @param dest address The destination address of the funds + * @param amount uint 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];