diff --git a/contracts/IColony.sol b/contracts/IColony.sol index 909802f1eb..b5c22745a0 100644 --- a/contracts/IColony.sol +++ b/contracts/IColony.sol @@ -93,18 +93,18 @@ contract IColony { // Implemented in DSAuth.sol /// @notice Get the `Authority` for the colony /// @return The `Authority` contract address - function authority() public view returns (address); + function authority() public view returns (address authority); /// @notice Get the colony `owner` address. This should be 0x0 at all times /// @dev Used for testing. /// @return Address of the colony owner - function owner() public view returns (address); + function owner() public view returns (address owner); // Implemented in Colony.sol /// @notice Get the Colony contract version /// Starts from 1 and is incremented with every deployed contract change /// @return Version number - function version() public pure returns (uint256); + function version() public pure returns (uint256 version); /// @notice Upgrades a colony to a new Colony contract version `_newVersion` /// @dev Downgrades are not allowed, i.e. `_newVersion` should be higher than the currect colony version @@ -136,7 +136,7 @@ contract IColony { /// @notice Get the colony token /// @return Address of the token contract - function getToken() public view returns (address); + function getToken() public view returns (address tokenAddress); /// @notice Called once when the colony is created to initialise certain storage slot values /// @param _network Address of the colony network @@ -163,7 +163,7 @@ contract IColony { /// @dev Calls `IColonyNetwork.addSkill` /// @param _parentSkillId Id of the skill under which the new skill will be added /// @return Id of the added skill - function addGlobalSkill(uint256 _parentSkillId) public returns (uint256); + function addGlobalSkill(uint256 _parentSkillId) public returns (uint256 skillId); /// @notice Add a colony domain, and its respective local skill under skill with id `_parentSkillId` /// New funding pot is created and associated with the domain here @@ -174,11 +174,11 @@ contract IColony { /// @param _id Id of the domain which details to get /// @return The domain "local" skill id /// @return The domain's funding pot id - function getDomain(uint256 _id) public view returns (uint256, uint256); + function getDomain(uint256 _id) public view returns (uint256 skillId, uint256 potId); /// @notice Get the number of domains in the colony /// @return The domain count. Min 1 as the root domain is created at the same time as the colony - function getDomainCount() public view returns (uint256); + function getDomainCount() public view returns (uint256 count); /// @notice Helper function that can be used by a client to verify the correctness of a patricia proof they have been supplied with. /// @param key The key of the element the proof is for. @@ -190,7 +190,7 @@ contract IColony { /// While public, likely only to be used by the Colony contracts, as it checks that the user is proving their own /// reputation in the current colony. The `verifyProof` function can be used to verify any proof, though this function /// is not currently exposed on the Colony's EtherRouter. - function verifyReputationProof(bytes key, bytes value, uint256 branchMask, bytes32[] siblings) public view returns (bool); + function verifyReputationProof(bytes key, bytes value, uint256 branchMask, bytes32[] siblings) public view returns (bool isValid); // Implemented in ColonyTask.sol /// @notice Make a new task in the colony. Secured function to authorised members @@ -200,12 +200,12 @@ contract IColony { /// @notice Get the number of tasks in the colony /// @return The task count - function getTaskCount() public view returns (uint256); + function getTaskCount() public view returns (uint256 count); /// @notice Starts from 0 and is incremented on every co-reviewed task change via `executeTaskChange` call /// @param _id Id of the task /// @return The current task change nonce value - function getTaskChangeNonce(uint256 _id) public view returns (uint256); + function getTaskChangeNonce(uint256 _id) public view returns (uint256 nonce); /// @notice Executes a task update transaction `_data` which is approved and signed by two of its roles (e.g. manager and worker) /// using the detached signatures for these users. @@ -275,19 +275,19 @@ contract IColony { /// @param _salt Salt value /// @param _value Value to hide /// @return `keccak256` hash of joint _salt and _value - function generateSecret(bytes32 _salt, uint256 _value) public pure returns (bytes32); + function generateSecret(bytes32 _salt, uint256 _value) public pure returns (bytes32 secret); /// @notice Get the `ColonyStorage.RatingSecrets` for task `_id` /// @param _id Id of the task /// @return Number of secrets /// @return Timestamp of the last submitted rating secret - function getTaskWorkRatings(uint256 _id) public view returns (uint256, uint256); + function getTaskWorkRatings(uint256 _id) public view returns (uint256 nSecrets, uint256 lastSubmittedAt); /// @notice Get the rating secret submitted for role `_role` in task `_id` /// @param _id Id of the task /// @param _role Id of the role, as defined in `ColonyStorage` `MANAGER`, `EVALUATOR` and `WORKER` constants /// @return Rating secret `bytes32` value - function getTaskWorkRatingSecret(uint256 _id, uint8 _role) public view returns (bytes32); + function getTaskWorkRatingSecret(uint256 _id, uint8 _role) public view returns (bytes32 secret); /// @notice Assigning manager role /// Current manager and user we want to assign role to both need to agree @@ -378,7 +378,7 @@ contract IColony { /// @return Deliverable submission timestamp /// @return Task domain id, default is root colony domain with id 1 /// @return Array of global skill ids assigned to task - function getTask(uint256 _id) public view returns (bytes32, bytes32, bool, bool, uint256, uint256, uint256, uint256, uint256, uint256[]); + function getTask(uint256 _id) public view returns (bytes32 specificationHash, bytes32 deliverableHash, bool finalized, bool cancelled, uint256 dueDate, uint256 payoutsWeCannotMake, uint256 potId, uint256 deliverableTimestamp, uint256 domainId, uint256[] skillIds); /// @notice Get the `Role` properties back for role `_role` in task `_id` /// @param _id Id of the task @@ -386,29 +386,29 @@ contract IColony { /// @return Address of the user for the given role /// @return Whether the user failed to rate their counterpart /// @return Rating the user received - function getTaskRole(uint256 _id, uint8 _role) public view returns (address, bool, uint8); + function getTaskRole(uint256 _id, uint8 _role) public view returns (address user, bool rateFail, uint8 rating); // Implemented in ColonyFunding.sol /// @notice Return 1 / the fee to pay to the network. e.g. if the fee is 1% (or 0.01), return 100 /// @return The inverse of the network fee - function getFeeInverse() public pure returns (uint256); + function getFeeInverse() public pure returns (uint256 feeInverse); /// @notice Return 1 / the reward to pay out from revenue. e.g. if the fee is 1% (or 0.01), return 100 /// @return The inverse of the reward - function getRewardInverse() public pure returns (uint256); + function getRewardInverse() public pure returns (uint256 rewardInverse); /// @notice Get payout amount in `_token` denomination for role `_role` in task `_id` /// @param _id Id of the task /// @param _role Id of the role, as defined in `ColonyStorage` `MANAGER`, `EVALUATOR` and `WORKER` constants /// @param _token Address of the token, `0x0` value indicates Ether /// @return Payout amount - function getTaskPayout(uint256 _id, uint256 _role, address _token) public view returns (uint256); + function getTaskPayout(uint256 _id, uint256 _role, address _token) public view returns (uint256 amount); /// @notice Get total payout amount in `_token` denomination for task `_id` /// @param _id Id of the task /// @param _token Address of the token, `0x0` value indicates Ether /// @return Payout amount - function getTotalTaskPayout(uint256 _id, address _token) public view returns (uint256); + function getTotalTaskPayout(uint256 _id, address _token) public view returns (uint256 amount); /// @notice Set `_token` payout for manager in task `_id` to `_amount` /// @param _id Id of the task @@ -465,7 +465,7 @@ contract IColony { /// @return Total amount of tokens taken aside for reward payout /// @return Token address /// @return Block number at the time of creation - function getRewardPayoutInfo(uint256 _payoutId) public view returns (bytes32, uint256, uint256, address, uint256); + function getRewardPayoutInfo(uint256 _payoutId) public view returns (bytes32 reputationState, uint256 totalTokens, uint256 amount, address tokenAddress, uint256 blockTimestamp); /// @notice Finalises the reward payout. Allows creation of next reward payouts for token that has been used in `_payoutId` /// Can only be called when reward payout cycle is finished i.e when 60 days have passed from its creation @@ -476,7 +476,7 @@ contract IColony { /// @param _potId Id of the funding pot /// @param _token Address of the token, `0x0` value indicates Ether /// @return Funding pot balance - function getPotBalance(uint256 _potId, address _token) public view returns (uint256); + function getPotBalance(uint256 _potId, address _token) public view returns (uint256 balance); /// @notice Move a given amount: `_amount` of `_token` funds from funding pot with id `_fromPot` to one with id `_toPot`. /// Secured function to authorised members @@ -494,5 +494,5 @@ contract IColony { /// @notice Get the total amount of tokens `_token` minus amount reserved to be paid to the reputation and token holders as rewards /// @param _token Address of the token, `0x0` value indicates Ether /// @return Total amount of tokens in pots other than the rewards pot (id 0) - function getNonRewardPotsTotal(address _token) public view returns (uint256); + function getNonRewardPotsTotal(address _token) public view returns (uint256 amount); } diff --git a/contracts/IColonyNetwork.sol b/contracts/IColonyNetwork.sol index de0c79db37..0241fd4b3c 100644 --- a/contracts/IColonyNetwork.sol +++ b/contracts/IColonyNetwork.sol @@ -44,16 +44,16 @@ contract IColonyNetwork { /// @notice Get the Meta Colony address /// @return The Meta colony address, if no colony was found, returns 0x0 - function getMetaColony() public view returns (address); + function getMetaColony() public view returns (address colonyAddress); /// @notice Get the number of colonies in the network /// @return The colony count - function getColonyCount() public view returns (uint256); + function getColonyCount() public view returns (uint256 count); /// @notice Check if specific address is a colony created on colony network /// @param _colony Address of the colony /// @return true if specified address is a colony, otherwise false - function isColony(address _colony) public view returns (bool); + function isColony(address _colony) public view returns (bool isColony); /// @notice Adds a new skill to the global or local skills tree, under skill `_parentSkillId` /// Only the Meta Colony is allowed to add a global skill, called via `IColony.addGlobalSkill` @@ -62,18 +62,18 @@ contract IColonyNetwork { /// @param _parentSkillId Id of the skill under which the new skill will be added /// @param _globalSkill true if the new skill is global, false if it is local /// @return Id of the added skill - function addSkill(uint256 _parentSkillId, bool _globalSkill) public returns (uint256); + function addSkill(uint256 _parentSkillId, bool _globalSkill) public returns (uint256 skillId); /// @notice Get the `nParents` and `nChildren` of skill with id `_skillId` /// @param _skillId Id of the skill /// @return uint256 `skill.nParents` i.e. the number of parent skills of skill with id `_skillId` /// @return uint256 `skill.nChildren` i.e. the number of child skills of skill with id `_skillId` - function getSkill(uint256 _skillId) public view returns (uint256, uint256); + function getSkill(uint256 _skillId) public view returns (uint256 nParents, uint256 nChildren); /// @notice Checks if skill with id `_skillId` is a global skill /// @param _skillId Id of the skill /// @return true if skill with id `_skillId` is a global skill, false otherwise - function isGlobalSkill(uint256 _skillId) public view returns (bool); + function isGlobalSkill(uint256 _skillId) public view returns (bool isGlobalSkill); /// @notice Adds a reputation update entry to log /// @dev Errors if it is called by anyone but a colony or if skill with id `_skillId` does not exist or @@ -84,12 +84,12 @@ contract IColonyNetwork { /// @notice Get the number of skills in the network including both global and local skills /// @return The skill count - function getSkillCount() public view returns (uint256); + function getSkillCount() public view returns (uint256 count); /// @notice Get the id of the root global skill /// @dev This is set once when the Meta Colony is created /// @return The root global skill id - function getRootGlobalSkillId() public view returns (uint256); + function getRootGlobalSkillId() public view returns (uint256 skillId); /// @notice Sets the token locking address /// This is only set once, and can't be changed afterwards @@ -98,7 +98,7 @@ contract IColonyNetwork { /// @notice Get token locking contract address /// @return Token locking contract address - function getTokenLocking() public view returns (address); + function getTokenLocking() public view returns (address lockingAddress); /// @notice Create the Meta Colony, same as a normal colony plus the root skill /// @param _tokenAddress Address of the CLNY token @@ -110,7 +110,7 @@ contract IColonyNetwork { /// Additionally token can optionally support `mint` as defined in `ERC20Extended` /// Support for `mint` in mandatory only for the Meta Colony Token /// @return Address of the newly created colony - function createColony(address _tokenAddress) public returns (address); + function createColony(address _tokenAddress) public returns (address colonyAddress); /// @notice Adds a new Colony contract version and the address of associated `_resolver` contract. Secured function to authorised members /// @param _version The new Colony contract version @@ -120,35 +120,35 @@ contract IColonyNetwork { /// @notice Get a colony address by its Id in the network /// @param _id Id of the colony to get /// @return The colony address, if no colony was found, returns 0x0 - function getColony(uint256 _id) public view returns (address); + function getColony(uint256 _id) public view returns (address colonyAddress); /// @notice Returns the latest Colony contract version. This is the version used to create all new colonies /// @return The current / latest Colony contract version - function getCurrentColonyVersion() public view returns (uint256); + function getCurrentColonyVersion() public view returns (uint256 version); /// @notice Get the id of the parent skill at index `_parentSkillIndex` for skill with Id `_skillId` /// @param _skillId Id of the skill /// @param _parentSkillIndex Index of the `skill.parents` array to get /// Note that not all parent skill ids are stored here. See `Skill.parents` member for definition on which parents are stored /// @return Skill Id of the requested parent skill - function getParentSkillId(uint256 _skillId, uint256 _parentSkillIndex) public view returns (uint256); + function getParentSkillId(uint256 _skillId, uint256 _parentSkillIndex) public view returns (uint256 skillId); /// @notice Get the id of the child skill at index `_childSkillIndex` for skill with Id `_skillId` /// @param _skillId Id of the skill /// @param _childSkillIndex Index of the `skill.children` array to get /// @return Skill Id of the requested child skill - function getChildSkillId(uint256 _skillId, uint256 _childSkillIndex) public view returns (uint256); + function getChildSkillId(uint256 _skillId, uint256 _childSkillIndex) public view returns (uint256 skillId); /// @notice Get the address of either the active or inactive reputation mining cycle, based on `active`. The active reputation mining cycle /// is the one currently under consideration by reputation miners. The inactive reputation cycle is the one with the log that is being appended to /// @param _active Whether the user wants the active or inactive reputation mining cycle /// @return address of active or inactive ReputationMiningCycle - function getReputationMiningCycle(bool _active) public view returns (address); + function getReputationMiningCycle(bool _active) public view returns (address repMiningCycleAddress); /// @notice Get the `Resolver` address for Colony contract version `_version` /// @param _version The Colony contract version /// @return Address of the `Resolver` contract - function getColonyVersionResolver(uint256 _version) public view returns (address); + function getColonyVersionResolver(uint256 _version) public view returns (address resolverAddress); /// @notice Allow a reputation miner to stake an `_amount` of CLNY tokens, which is required /// before they can submit a new reputation root hash via `ReputationMiningCycle.submitNewHash` @@ -164,7 +164,7 @@ contract IColonyNetwork { /// @notice Get the amount of staked CLNY tokens for user `_user` /// @param _user Address of the user whose balance we want to get /// @return User stake balance - function getStakedBalance(address _user) public view returns (uint256); + function getStakedBalance(address _user) public view returns (uint256 balance); /// @notice Set a new Reputation root hash and starts a new mining cycle. Can only be called by the ReputationMiningCycle contract. /// @param newHash The reputation root hash @@ -183,12 +183,12 @@ contract IColonyNetwork { /// @notice Get the root hash of the current reputation state tree /// @return bytes32 The current Reputation Root Hash - function getReputationRootHash() public view returns (bytes32); + function getReputationRootHash() public view returns (bytes32 rootHash); /// @notice Get the number of nodes in the current reputation state tree. /// @dev I cannot see a reason why a user's client would need to call this - only stored to help with some edge cases in reputation mining dispute resolution /// @return uint256 The number of nodes in the state tree - function getReputationRootHashNNodes() public view returns (uint256); + function getReputationRootHashNNodes() public view returns (uint256 nNodes); /// @notice Create and start a new `DutchAuction` for the entire amount of `_token` owned by the Colony Network /// @param _token Address of the token held by the network to be auctioned diff --git a/contracts/IReputationMiningCycle.sol b/contracts/IReputationMiningCycle.sol index 0e58849a41..ab24ce4e33 100644 --- a/contracts/IReputationMiningCycle.sol +++ b/contracts/IReputationMiningCycle.sol @@ -43,7 +43,8 @@ contract IReputationMiningCycle { /// @param submitter The address that submitted the hash /// @param entryIndex The index of the entry that they used to submit the hash /// @param newHash The hash that they submitted - function getEntryHash(address submitter, uint256 entryIndex, bytes32 newHash) public pure returns (bytes32); + /// @return entryHash The hash for the corresponding entry + function getEntryHash(address submitter, uint256 entryIndex, bytes32 newHash) public pure returns (bytes32 entryHash); /// @notice Resets the timestamp that the submission window opens to `now` /// @dev only allowed to be called by ColonyNetwork @@ -149,7 +150,7 @@ contract IReputationMiningCycle { /// @notice Get the length of the ReputationUpdateLog stored on this instance of the ReputationMiningCycle contract /// @return nUpdates - function getReputationUpdateLogLength() public view returns (uint); + function getReputationUpdateLogLength() public view returns (uint nUpdates); /// @notice Get the `ReputationLogEntry` at index `_id` /// @param _id The reputation log members array index of the entry to get @@ -159,7 +160,7 @@ contract IReputationMiningCycle { /// @return colony The address of the colony the reputation is being affected in /// @return nUpdates The number of updates this log entry implies (including updates to parents, children and colony-wide totals thereof) /// @return nPreviousUpdates The number of updates all previous entries in the log imply (including reputation decays, updates to parents, children, and colony-wide totals thereof) - function getReputationUpdateLogEntry(uint256 _id) public view returns (address, int256, uint256, address, uint256, uint256); + function getReputationUpdateLogEntry(uint256 _id) public view returns (address user, int256 amount, uint256 skillId, address colony, uint256 nUpdates, uint256 nPreviousUpdates); /// @notice Start the reputation log with the rewards for the stakers who backed the accepted new reputation root hash. /// @param stakers The array of stakers addresses to receive the reward. @@ -170,5 +171,5 @@ contract IReputationMiningCycle { /// same address backed the same hash multiple times with different entries. function rewardStakersWithReputation(address[] stakers, address commonColonyAddress, uint reward, uint miningSkillId) public; - function reputationMiningWindowOpenTimestamp() public view returns (uint); + function reputationMiningWindowOpenTimestamp() public view returns (uint timestamp); } diff --git a/contracts/ITokenLocking.sol b/contracts/ITokenLocking.sol index a4e0b22ae0..fa23e90596 100644 --- a/contracts/ITokenLocking.sol +++ b/contracts/ITokenLocking.sol @@ -10,12 +10,12 @@ contract ITokenLocking { /// @notice Get ColonyNetwork address /// @return ColonyNetwork address - function getColonyNetwork() public view returns (address); + function getColonyNetwork() public view returns (address networkAddress); /// @notice Locks everyones' tokens on `_token` address /// @param _token Address of the token we want to lock /// @return Updated total token lock count - function lockToken(address _token) public returns (uint256); + function lockToken(address _token) public returns (uint256 lockCount); /// @notice Increments the lock counter to `_lockId` for the `_user` if user's lock count is less than `_lockId` by 1. /// Can only be called by a colony @@ -41,12 +41,12 @@ contract ITokenLocking { /// @notice Get global lock count for a specific token /// @param _token Address of the token /// @return Global token lock count - function getTotalLockCount(address _token) public view returns (uint256); + function getTotalLockCount(address _token) public view returns (uint256 lockCount); /// @notice Get user token lock info (lock count and deposited amount) /// @param _token Address of the token /// @param _user Address of the user /// @return User's token lock count /// @return User's deposited amount - function getUserLock(address _token, address _user) public view returns (uint256, uint256); + function getUserLock(address _token, address _user) public view returns (uint256 lockCount, uint256 amount); } diff --git a/contracts/PatriciaTree/IPatriciaTree.sol b/contracts/PatriciaTree/IPatriciaTree.sol index 78c53581be..226440da71 100644 --- a/contracts/PatriciaTree/IPatriciaTree.sol +++ b/contracts/PatriciaTree/IPatriciaTree.sol @@ -12,7 +12,7 @@ contract IPatriciaTree { /// @notice Get the root hash /// @dev This value is a keccak256 hash of the rootEdge: `keccak256(Edge.node, Edge.label.length, Edge.label.data)` /// @return The `bytes32` hash value - function getRootHash() public view returns (bytes32); + function getRootHash() public view returns (bytes32 rootHash); /// @notice Get the root edge /// @return The root `Data.Edge` @@ -30,7 +30,7 @@ contract IPatriciaTree { /// @notice Calculates and returns a root hash for the `key`, `value`, `branchMask` and `siblings` /// @return The calculated hash - function getImpliedRoot(bytes key, bytes value, uint branchMask, bytes32[] siblings) public pure returns (bytes32); + function getImpliedRoot(bytes key, bytes value, uint branchMask, bytes32[] siblings) public pure returns (bytes32 rootHash); /// @notice Insert the `key`/`value`in the appropriate place in the tree function insert(bytes key, bytes value) public;