From fc43409afb770a145a973e2494fc89e5dfc02ec3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?James=20Lefr=C3=A8re?= <james@colony.io>
Date: Mon, 9 Jul 2018 11:14:20 +0200
Subject: [PATCH 1/3] Remove return type

* `startNextRewardPayout` appears to have no return value; correct the interface signature
---
 contracts/IColony.sol | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/contracts/IColony.sol b/contracts/IColony.sol
index b3f0570241..909802f1eb 100644
--- a/contracts/IColony.sol
+++ b/contracts/IColony.sol
@@ -438,8 +438,8 @@ contract IColony {
 
   /// @notice Start next reward payout for `_token`. All funds in the reward pot for `_token` will become unavailable.
   /// All tokens will be locked, and can be unlocked by calling `waiveRewardPayout` or `claimRewardPayout`.
-  /// @param _token Addess of the token used for reward payout
-  function startNextRewardPayout(address _token) public returns (uint256);
+  /// @param _token Address of the token used for reward payout
+  function startNextRewardPayout(address _token) public;
 
   /// @notice Claim the reward payout at `_payoutId`. User needs to provide their reputation and colony-wide reputation
   /// which will be proven via Merkle proof inside this function.

From 4a46277dcfbf18d4c4f37011798b2ad0483a88d6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?James=20Lefr=C3=A8re?= <james@colony.io>
Date: Mon, 9 Jul 2018 11:40:02 +0200
Subject: [PATCH 2/3] Return variable names

* Add names for every return variable for the interface contracts
---
 contracts/IColony.sol                    | 44 ++++++++++++------------
 contracts/IColonyNetwork.sol             | 38 ++++++++++----------
 contracts/IReputationMiningCycle.sol     |  9 ++---
 contracts/ITokenLocking.sol              |  8 ++---
 contracts/PatriciaTree/IPatriciaTree.sol |  4 +--
 5 files changed, 52 insertions(+), 51 deletions(-)

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;

From 215d8673c9a76f3a27087dbc28fd9248a0c4f854 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?James=20Lefr=C3=A8re?= <james@colony.io>
Date: Mon, 9 Jul 2018 12:18:48 +0200
Subject: [PATCH 3/3] Add NatSpec return names

* Specify variable names for every NatSpec `@return` entry (for the interface contracts)
---
 contracts/IColony.sol                    | 78 ++++++++++++------------
 contracts/IColonyNetwork.sol             | 40 ++++++------
 contracts/ITokenLocking.sol              | 10 +--
 contracts/PatriciaTree/IPatriciaTree.sol |  8 +--
 4 files changed, 68 insertions(+), 68 deletions(-)

diff --git a/contracts/IColony.sol b/contracts/IColony.sol
index b5c22745a0..3ee519854a 100644
--- a/contracts/IColony.sol
+++ b/contracts/IColony.sol
@@ -92,18 +92,18 @@ contract IColony {
 
   // Implemented in DSAuth.sol
   /// @notice Get the `Authority` for the colony
-  /// @return The `Authority` contract address
+  /// @return authority The `Authority` contract 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
+  /// @return owner Address of the colony owner
   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
+  /// @return version Version number
   function version() public pure returns (uint256 version);
 
   /// @notice Upgrades a colony to a new Colony contract version `_newVersion`
@@ -135,7 +135,7 @@ contract IColony {
   function removeAdminRole(address _user) public;
 
   /// @notice Get the colony token
-  /// @return Address of the token contract
+  /// @return tokenAddress Address of the token contract
   function getToken() public view returns (address tokenAddress);
 
   /// @notice Called once when the colony is created to initialise certain storage slot values
@@ -162,7 +162,7 @@ contract IColony {
   /// Can only be called from the Meta Colony
   /// @dev Calls `IColonyNetwork.addSkill`
   /// @param _parentSkillId Id of the skill under which the new skill will be added
-  /// @return Id of the added skill
+  /// @return skillId Id of the added skill
   function addGlobalSkill(uint256 _parentSkillId) public returns (uint256 skillId);
 
   /// @notice Add a colony domain, and its respective local skill under skill with id `_parentSkillId`
@@ -172,12 +172,12 @@ contract IColony {
 
   /// @notice Get the domain's local skill and funding pot id
   /// @param _id Id of the domain which details to get
-  /// @return The domain "local" skill id
-  /// @return The domain's funding pot id
+  /// @return skillId The domain "local" skill id
+  /// @return potId The domain's funding pot id
   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
+  /// @return count The domain count. Min 1 as the root domain is created at the same time as the colony
   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.
@@ -185,7 +185,7 @@ contract IColony {
   /// @param value The value of the element that the proof is for.
   /// @param branchMask The branchmask of the proof
   /// @param siblings The siblings of the proof
-  /// @return True if the proof is valid, false otherwise.
+  /// @return isValid True if the proof is valid, false otherwise.
   /// @dev For more detail about branchMask and siblings, examine the PatriciaTree implementation
   /// 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
@@ -199,12 +199,12 @@ contract IColony {
   function makeTask(bytes32 _specificationHash, uint256 _domainId) public;
 
   /// @notice Get the number of tasks in the colony
-  /// @return The task count
+  /// @return count The task count
   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
+  /// @return nonce The current task change nonce value
   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)
@@ -274,19 +274,19 @@ contract IColony {
   /// @notice Helper function used to generage consistently the rating secret using salt value `_salt` and value to hide `_value`
   /// @param _salt Salt value
   /// @param _value Value to hide
-  /// @return `keccak256` hash of joint _salt and _value
+  /// @return secret `keccak256` hash of joint _salt and _value
   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
+  /// @return nSecrets Number of secrets
+  /// @return lastSubmittedAt Timestamp of the last submitted rating secret
   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
+  /// @return secret Rating secret `bytes32` value
   function getTaskWorkRatingSecret(uint256 _id, uint8 _role) public view returns (bytes32 secret);
 
   /// @notice Assigning manager role
@@ -368,46 +368,46 @@ contract IColony {
 
   /// @notice Get a task with id `_id`
   /// @param _id Id of the task
-  /// @return Task brief hash
-  /// @return Task deliverable hash
-  /// @return Finalised property
-  /// @return Cancelled property
-  /// @return Due date
-  /// @return Number of payouts that cannot be completed with the current task funding
-  /// @return Id of funding pot for task
-  /// @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
+  /// @return specificationHash Task brief hash
+  /// @return deliverableHash Task deliverable hash
+  /// @return finalized Finalised property
+  /// @return cancelled Cancelled property
+  /// @return dueDate Due date
+  /// @return payoutsWeCannotMake Number of payouts that cannot be completed with the current task funding
+  /// @return potId Id of funding pot for task
+  /// @return deliverableTimestamp Deliverable submission timestamp
+  /// @return domainId Task domain id, default is root colony domain with id 1
+  /// @return skillIds Array of global skill ids assigned to task
   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
   /// @param _role Id of the role, as defined in `ColonyStorage` `MANAGER`, `EVALUATOR` and `WORKER` constants
-  /// @return Address of the user for the given role
-  /// @return Whether the user failed to rate their counterpart
-  /// @return Rating the user received
+  /// @return user Address of the user for the given role
+  /// @return rateFail Whether the user failed to rate their counterpart
+  /// @return rating Rating the user received
   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
+  /// @return feeInverse The inverse of the network fee
   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
+  /// @return rewardInverse The inverse of the reward
   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
+  /// @return amount Payout amount
   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
+  /// @return amount Payout amount
   function getTotalTaskPayout(uint256 _id, address _token) public view returns (uint256 amount);
 
   /// @notice Set `_token` payout for manager in task `_id` to `_amount`
@@ -460,11 +460,11 @@ contract IColony {
 
   /// @notice Get useful information about specific reward payout
   /// @param _payoutId Id of the reward payout
-  /// @return Reputation root hash at the time of creation
-  /// @return Total colony tokens at the time of creation
-  /// @return Total amount of tokens taken aside for reward payout
-  /// @return Token address
-  /// @return Block number at the time of creation
+  /// @return reputationState Reputation root hash at the time of creation
+  /// @return totalTokens Total colony tokens at the time of creation
+  /// @return amount Total amount of tokens taken aside for reward payout
+  /// @return tokenAddress Token address
+  /// @return blockTimestamp Block number at the time of creation
   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`
@@ -475,7 +475,7 @@ contract IColony {
   /// @notice Get the `_token` balance of pot with id `_potId`
   /// @param _potId Id of the funding pot
   /// @param _token Address of the token, `0x0` value indicates Ether
-  /// @return Funding pot balance
+  /// @return balance Funding pot balance
   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`.
@@ -493,6 +493,6 @@ 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)
+  /// @return amount Total amount of tokens in pots other than the rewards pot (id 0)
   function getNonRewardPotsTotal(address _token) public view returns (uint256 amount);
 }
diff --git a/contracts/IColonyNetwork.sol b/contracts/IColonyNetwork.sol
index 0241fd4b3c..a556802e24 100644
--- a/contracts/IColonyNetwork.sol
+++ b/contracts/IColonyNetwork.sol
@@ -43,16 +43,16 @@ contract IColonyNetwork {
   event AuctionCreated(address auction, address token, uint256 quantity);
 
   /// @notice Get the Meta Colony address
-  /// @return The Meta colony address, if no colony was found, returns 0x0
+  /// @return colonyAddress The Meta colony address, if no colony was found, returns 0x0
   function getMetaColony() public view returns (address colonyAddress);
 
   /// @notice Get the number of colonies in the network
-  /// @return The colony count
+  /// @return count The colony count
   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
+  /// @return isColony true if specified address is a colony, otherwise false
   function isColony(address _colony) public view returns (bool isColony);
 
   /// @notice Adds a new skill to the global or local skills tree, under skill `_parentSkillId`
@@ -61,18 +61,18 @@ contract IColonyNetwork {
   /// @dev Errors if the parent skill does not exist or if this is called by an unauthorised sender
   /// @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
+  /// @return skillId Id of the added skill
   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`
+  /// @return nParents uint256 `skill.nParents` i.e. the number of parent skills of skill with id `_skillId`
+  /// @return nChildren uint256 `skill.nChildren` i.e. the number of child skills of skill with id `_skillId`
   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
+  /// @return isGlobalSkill true if skill with id `_skillId` is a global skill, false otherwise
   function isGlobalSkill(uint256 _skillId) public view returns (bool isGlobalSkill);
 
   /// @notice Adds a reputation update entry to log
@@ -83,12 +83,12 @@ contract IColonyNetwork {
   function appendReputationUpdateLog(address _user, int256 _amount, uint256 _skillId) public;
 
   /// @notice Get the number of skills in the network including both global and local skills
-  /// @return The skill count
+  /// @return count The skill count
   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
+  /// @return skillId, The root global skill id
   function getRootGlobalSkillId() public view returns (uint256 skillId);
 
   /// @notice Sets the token locking address
@@ -97,7 +97,7 @@ contract IColonyNetwork {
   function setTokenLocking(address _tokenLockingAddress) public;
 
   /// @notice Get token locking contract address
-  /// @return Token locking contract address
+  /// @return lockingAddress Token locking contract address
   function getTokenLocking() public view returns (address lockingAddress);
 
   /// @notice Create the Meta Colony, same as a normal colony plus the root skill
@@ -109,7 +109,7 @@ contract IColonyNetwork {
   /// @param _tokenAddress Address of an ERC20 token to serve as the colony token
   /// 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
+  /// @return colonyAddress Address of the newly created colony
   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
@@ -119,35 +119,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
+  /// @return colonyAddress The colony address, if no colony was found, returns 0x0
   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
+  /// @return version The current / latest Colony contract version
   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
+  /// @return skillId Skill Id of the requested parent skill
   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
+  /// @return skillId Skill Id of the requested child skill
   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
+  /// @return repMiningCycleAddress address of active or inactive ReputationMiningCycle
   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
+  /// @return resolverAddress Address of the `Resolver` contract
   function getColonyVersionResolver(uint256 _version) public view returns (address resolverAddress);
 
   /// @notice Allow a reputation miner to stake an `_amount` of CLNY tokens, which is required
@@ -163,7 +163,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
+  /// @return balance User stake balance
   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.
@@ -182,12 +182,12 @@ contract IColonyNetwork {
   function punishStakers(address[] stakers) public;
 
   /// @notice Get the root hash of the current reputation state tree
-  /// @return bytes32 The current Reputation Root Hash
+  /// @return rootHash bytes32 The current Reputation Root Hash
   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
+  /// @return nNodes uint256 The number of nodes in the state tree
   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
diff --git a/contracts/ITokenLocking.sol b/contracts/ITokenLocking.sol
index fa23e90596..21dd0165a0 100644
--- a/contracts/ITokenLocking.sol
+++ b/contracts/ITokenLocking.sol
@@ -9,12 +9,12 @@ contract ITokenLocking {
   function setColonyNetwork(address _colonyNetwork) public;
 
   /// @notice Get ColonyNetwork address
-  /// @return ColonyNetwork address
+  /// @return networkAddress ColonyNetwork 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
+  /// @return lockCount Updated total token lock count
   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.
@@ -40,13 +40,13 @@ contract ITokenLocking {
 
   /// @notice Get global lock count for a specific token
   /// @param _token Address of the token
-  /// @return Global token lock count
+  /// @return lockCount Global token lock count
   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
+  /// @return lockCount User's token lock count
+  /// @return amount User's deposited amount
   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 226440da71..fd3d8d43d9 100644
--- a/contracts/PatriciaTree/IPatriciaTree.sol
+++ b/contracts/PatriciaTree/IPatriciaTree.sol
@@ -11,16 +11,16 @@ 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
+  /// @return rootHash The `bytes32` hash value
   function getRootHash() public view returns (bytes32 rootHash);
 
   /// @notice Get the root edge
-  /// @return The root `Data.Edge`
+  /// @return e The root `Data.Edge`
   function getRootEdge() public view returns (Data.Edge e);
 
   /// @notice Get the node with the given key
   /// @param hash The `keccak256` hash of the actual key
-  /// @return `Data.Node` for key `hash`
+  /// @return n `Data.Node` for key `hash`
   function getNode(bytes32 hash) public view returns (Data.Node n);
 
   /// @notice Returns the Merkle-proof for the given `key`
@@ -29,7 +29,7 @@ contract IPatriciaTree {
   function getProof(bytes key) public view returns (uint branchMask, bytes32[] _siblings);
 
   /// @notice Calculates and returns a root hash for the `key`, `value`, `branchMask` and `siblings`
-  /// @return The calculated hash
+  /// @return rootHash The calculated hash
   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