Add NatSpec return names

* Specify variable names for every NatSpec `@return` entry (for the interface contracts)

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,20 +172,20 @@ 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.
   /// @param key The key of the element the proof is for.
   /// @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)
@@ -260,19 +260,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
@@ -354,46 +354,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`
@@ -446,11 +446,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`
@@ -461,7 +461,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`.
@@ -479,6 +479,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);
 }

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