diff --git a/contracts/colony/IColony.sol b/contracts/colony/IColony.sol
index 2a9264a01e..c35e65d403 100644
--- a/contracts/colony/IColony.sol
+++ b/contracts/colony/IColony.sol
@@ -61,8 +61,8 @@ interface IColony is ColonyDataTypes, IRecovery, IBasicMetaTransaction {
   /// @return tokenAddress Address of the token contract
   function getToken() external view returns (address tokenAddress);
 
+  /// @notice @deprecated
   /// @notice Execute arbitrary transaction on behalf of the Colony
-  /// DEPRECATED
   /// @param _to Contract to receive the function call (cannot be this contract, network or token locking)
   /// @param _action Bytes array encoding the function call and arguments
   /// @return success Boolean indicating whether the transaction succeeded
@@ -250,7 +250,8 @@ interface IColony is ColonyDataTypes, IRecovery, IBasicMetaTransaction {
   function mintTokensFor(address _guy, uint256 _wad) external;
 
   /// @notice Lock the colony's token. Can only be called by a network-managed extension.
-  function lockToken() external returns (uint256);
+  /// @return timesLocked The amount of times the token was locked
+  function lockToken() external returns (uint256 timesLocked);
 
   /// @notice Unlock the colony's token for a user. Can only be called by a network-managed extension.
   /// @param user The user to unlock
@@ -376,7 +377,8 @@ interface IColony is ColonyDataTypes, IRecovery, IBasicMetaTransaction {
   /// @param _newOwner New owner of expenditure
   function transferExpenditure(uint256 _id, address _newOwner) external;
 
-  /// @notice DEPRECATED Updates the expenditure owner. Can only be called by Arbitration role.
+  /// @notice @deprecated
+  /// @notice Updates the expenditure owner. Can only be called by Arbitration role.
   /// @dev This is now deprecated and will be removed in a future version
   /// @param _permissionDomainId The domainId in which I have the permission to take this action
   /// @param _childSkillIndex The index that the `_domainId` is relative to `_permissionDomainId`,
@@ -409,7 +411,7 @@ interface IColony is ColonyDataTypes, IRecovery, IBasicMetaTransaction {
   /// @param _metadata IPFS hash of the metadata
   function setExpenditureMetadata(uint256 _permissionDomainId, uint256 _childSkillIndex, uint256 _id, string memory _metadata) external;
 
-  /// @notice Deprecated
+  /// @notice @deprecated
   /// @notice Sets the recipient on an expenditure slot. Can only be called by expenditure owner.
   /// @param _id Id of the expenditure
   /// @param _slot Slot for the recipient address
@@ -422,7 +424,7 @@ interface IColony is ColonyDataTypes, IRecovery, IBasicMetaTransaction {
   /// @param _recipients Addresses of the recipients
   function setExpenditureRecipients(uint256 _id, uint256[] memory _slots, address payable[] memory _recipients) external;
 
-  /// @notice Deprecated
+  /// @notice @deprecated
   /// @notice Set the token payout on an expenditure slot. Can only be called by expenditure owner.
   /// @param _id Id of the expenditure
   /// @param _slot Number of the slot
@@ -437,7 +439,7 @@ interface IColony is ColonyDataTypes, IRecovery, IBasicMetaTransaction {
   /// @param _amounts Payout amounts
   function setExpenditurePayouts(uint256 _id, uint256[] memory _slots, address _token, uint256[] memory _amounts) external;
 
-  /// @notice Deprecated
+  /// @notice @deprecated
   /// @notice Sets the skill on an expenditure slot. Can only be called by expenditure owner.
   /// @param _id Expenditure identifier
   /// @param _slot Number of the slot
@@ -450,7 +452,7 @@ interface IColony is ColonyDataTypes, IRecovery, IBasicMetaTransaction {
   /// @param _skillIds Ids of the new skills to set
   function setExpenditureSkills(uint256 _id, uint256[] memory _slots, uint256[] memory _skillIds) external;
 
-  /// @notice Deprecated
+  /// @notice @deprecated
   /// @notice Sets the claim delay on an expenditure slot. Can only be called by expenditure owner.
   /// @param _id Expenditure identifier
   /// @param _slot Number of the slot
@@ -932,8 +934,7 @@ interface IColony is ColonyDataTypes, IRecovery, IBasicMetaTransaction {
   /// @param _permissionDomainId The domainId in which I have the permission to take this action
   /// @param _childSkillIndex The child index in _permissionDomainId where I will be taking this action
   /// @param _domainId The domain where I am taking this action, pointed to by _permissionDomainId and _childSkillIndex
-  /// @param _fromChildSkillIndex In the array of child skills for the skill associated with the domain pointed to by _permissionDomainId + _childSkillIndex,
-  ///         the index of the skill associated with the domain that contains _fromPot
+  /// @param _fromChildSkillIndex In the array of child skills for the skill associated with the domain pointed to by _permissionDomainId + _childSkillIndex, the index of the skill associated with the domain that contains _fromPot
   /// @param _toChildSkillIndex The same, but for the _toPot which the funds are being moved to
   /// @param _fromPot Funding pot id providing the funds
   /// @param _toPot Funding pot id receiving the funds
@@ -951,7 +952,7 @@ interface IColony is ColonyDataTypes, IRecovery, IBasicMetaTransaction {
     address _token
     ) external;
 
-  /// @notice DEPRECATED
+  /// @notice @deprecated
   /// @notice Move a given amount: `_amount` of `_token` funds from funding pot with id `_fromPot` to one with id `_toPot`.
   /// @param _permissionDomainId The domainId in which I have the permission to take this action
   /// @param _fromChildSkillIndex The child index in `_permissionDomainId` where we can find the domain for `_fromPotId`
@@ -1052,9 +1053,11 @@ interface IColony is ColonyDataTypes, IRecovery, IBasicMetaTransaction {
   /// @notice Get the current approval amount
   /// @param token The address of the token which was approved
   /// @param spender The account we have approved
+  /// @return amount The token approval amount
   function getTokenApproval(address token, address spender) external view returns (uint256 amount);
 
   /// @notice Get the current total approval amount across all spenders
   /// @param token The address of the token which was approved
+  /// @return amount The total token approval amount
   function getTotalTokenApproval(address token) external view returns (uint256 amount);
 }
diff --git a/contracts/colony/IMetaColony.sol b/contracts/colony/IMetaColony.sol
index 0f1452910d..a6e58b6f64 100644
--- a/contracts/colony/IMetaColony.sol
+++ b/contracts/colony/IMetaColony.sol
@@ -57,6 +57,7 @@ interface IMetaColony is IColony {
 
   /// @notice Called to set the total per-cycle reputation reward, which will be split between all miners.
   /// @dev Calls the corresponding function on the ColonyNetwork.
+  /// @param _amount The CLNY awarded per mining cycle to the miners
   function setReputationMiningCycleReward(uint256 _amount) external;
 
   /// @notice Add a new extension/version to the Extensions repository.
diff --git a/contracts/colonyNetwork/ColonyNetwork.sol b/contracts/colonyNetwork/ColonyNetwork.sol
index ce7dc04098..d88159eff2 100644
--- a/contracts/colonyNetwork/ColonyNetwork.sol
+++ b/contracts/colonyNetwork/ColonyNetwork.sol
@@ -197,7 +197,7 @@ contract ColonyNetwork is BasicMetaTransaction, ColonyNetworkStorage {
     return changed;
   }
 
-  // DEPRECATED
+  /// @notice @deprecated
   function deprecateSkill(uint256 _skillId) public stoppable {
     deprecateSkill(_skillId, true);
   }
diff --git a/contracts/colonyNetwork/ColonyNetworkDeployer.sol b/contracts/colonyNetwork/ColonyNetworkDeployer.sol
index 343119a6bc..235061f918 100644
--- a/contracts/colonyNetwork/ColonyNetworkDeployer.sol
+++ b/contracts/colonyNetwork/ColonyNetworkDeployer.sol
@@ -41,7 +41,7 @@ contract ColonyNetworkDeployer is ColonyNetworkStorage {
     emit MetaColonyCreated(metaColony, _tokenAddress, skillCount);
   }
 
-  // DEPRECATED, only deploys version 3 colonies.
+  /// @notice @deprecated only deploys version 3 colonies.
   function createColony(address _tokenAddress) public
   stoppable
   returns (address)
@@ -49,7 +49,7 @@ contract ColonyNetworkDeployer is ColonyNetworkStorage {
     return createColony(_tokenAddress, 3, "", "");
   }
 
-  // DEPRECATED, only deploys version 4 colonies.
+  /// @notice @deprecated only deploys version 4 colonies.
   function createColony(
     address _tokenAddress,
     uint256 _version, // solhint-disable-line no-unused-vars
diff --git a/contracts/colonyNetwork/IColonyNetwork.sol b/contracts/colonyNetwork/IColonyNetwork.sol
index d9ede6fabc..b11cbd0cc6 100644
--- a/contracts/colonyNetwork/IColonyNetwork.sol
+++ b/contracts/colonyNetwork/IColonyNetwork.sol
@@ -359,6 +359,7 @@ interface IColonyNetwork is ColonyNetworkDataTypes, IRecovery, IBasicMetaTransac
 
   /// @notice Get a token's status in the payout whitelist
   /// @param _token The token being queried
+  /// @return status Will be `true` if token is whitelisted
   function getPayoutWhitelist(address _token) external view returns (bool status);
 
   /// @notice Set a token's status in the payout whitelist
@@ -403,11 +404,12 @@ interface IColonyNetwork is ColonyNetworkDataTypes, IRecovery, IBasicMetaTransac
 
   /// @notice Called to set the total per-cycle reputation reward, which will be split between all miners.
   /// @dev Can only be called by the MetaColony.
+  /// @param _amount The CLNY awarded per mining cycle to the miners
   function setReputationMiningCycleReward(uint256 _amount) external;
 
   /// @notice Called to get the total per-cycle reputation mining reward.
-  /// @return The CLNY awarded per mining cycle to the miners.
-  function getReputationMiningCycleReward() external view returns (uint256);
+  /// @return amount The CLNY awarded per mining cycle to the miners
+  function getReputationMiningCycleReward() external view returns (uint256 amount);
 
   /// @notice Called to deploy a token.
   /// @dev This is more expensive than deploying a token directly, but is able to be done via
@@ -424,6 +426,7 @@ interface IColonyNetwork is ColonyNetworkDataTypes, IRecovery, IBasicMetaTransac
   /// @param _token The address of the otken
   /// @param _colony The address of the colony in control of the token
   /// @param allowedToTransfer An array of addresses that are allowed to transfer the token even if it's locked
+  /// @return The address of the newly deployed TokenAuthority
   function deployTokenAuthority(address _token, address _colony, address[] memory allowedToTransfer) external returns (address);
 
   /// @notice Called to give or remove another address's permission to mine on your behalf
@@ -433,7 +436,7 @@ interface IColonyNetwork is ColonyNetworkDataTypes, IRecovery, IBasicMetaTransac
 
   /// @notice Called to get the address _delegate is allowed to mine for
   /// @param _delegate The address that wants to mine
-  /// @return The address they are allowed to mine on behalf of
-  function getMiningDelegator(address _delegate) external view returns (address);
+  /// @return delegator The address they are allowed to mine on behalf of
+  function getMiningDelegator(address _delegate) external view returns (address delegator);
 
 }
diff --git a/contracts/extensions/VotingReputation.sol b/contracts/extensions/VotingReputation.sol
index 19ef57e212..2fa46faf95 100644
--- a/contracts/extensions/VotingReputation.sol
+++ b/contracts/extensions/VotingReputation.sol
@@ -296,7 +296,8 @@ contract VotingReputation is ColonyExtension, PatriciaTreeProofs, BasicMetaTrans
     emit MotionCreated(motionCount, msgSender(), _domainId);
   }
 
-  /// @notice Create a motion in the root domain (DEPRECATED)
+  /// @notice @deprecated
+  /// @notice Create a motion in the root domain
   /// @param _altTarget The contract to which we send the action (0x0 for the colony)
   /// @param _action A bytes array encoding a function call
   /// @param _key Reputation tree key for the root domain
@@ -316,7 +317,8 @@ contract VotingReputation is ColonyExtension, PatriciaTreeProofs, BasicMetaTrans
     createMotion(1, UINT256_MAX, _altTarget, _action, _key, _value, _branchMask, _siblings);
   }
 
-  /// @notice Create a motion in any domain (DEPRECATED)
+  /// @notice @deprecated
+  /// @notice Create a motion in any domain
   /// @param _domainId The domain where we vote on the motion
   /// @param _childSkillIndex The childSkillIndex pointing to the domain of the action
   /// @param _action A bytes array encoding a function call
diff --git a/contracts/tokenLocking/ITokenLocking.sol b/contracts/tokenLocking/ITokenLocking.sol
index 74336b4a2f..085e3d719b 100644
--- a/contracts/tokenLocking/ITokenLocking.sol
+++ b/contracts/tokenLocking/ITokenLocking.sol
@@ -50,7 +50,8 @@ interface ITokenLocking is TokenLockingDataTypes, IBasicMetaTransaction {
   /// @param _lockId Id of the lock user wants to increment to
   function incrementLockCounterTo(address _token, uint256 _lockId) external;
 
-  /// @notice DEPRECATED Deposit `_amount` of deposited tokens. Can only be called if user tokens are not locked.
+  /// @notice @deprecated
+  /// @notice Deposit `_amount` of deposited tokens. Can only be called if user tokens are not locked.
   /// Before calling this function user has to allow that their tokens can be transferred by token locking contract.
   /// @param _token Address of the token to deposit
   /// @param _amount Amount to deposit
@@ -76,7 +77,8 @@ interface ITokenLocking is TokenLockingDataTypes, IBasicMetaTransaction {
   /// @param _force Pass true to forcibly unlock the token
   function transfer(address _token, uint256 _amount, address _recipient, bool _force) external;
 
-  /// @notice DEPRECATED Withdraw `_amount` of deposited tokens. Can only be called if user tokens are not locked.
+  /// @notice @deprecated
+  /// @notice Withdraw `_amount` of deposited tokens. Can only be called if user tokens are not locked.
   /// @param _token Address of the token to withdraw from
   /// @param _amount Amount to withdraw
   function withdraw(address _token, uint256 _amount) external;
diff --git a/docs/_Interface_IColony.md b/docs/_Interface_IColony.md
index e64769199a..2b6c125577 100644
--- a/docs/_Interface_IColony.md
+++ b/docs/_Interface_IColony.md
@@ -994,7 +994,7 @@ Get the current approval amount
 
 |Name|Type|Description|
 |---|---|---|
-|amount|uint256|
+|amount|uint256|The token approval amount
 
 ### `getTotalTokenApproval`
 
@@ -1011,7 +1011,7 @@ Get the current total approval amount across all spenders
 
 |Name|Type|Description|
 |---|---|---|
-|amount|uint256|
+|amount|uint256|The total token approval amount
 
 ### `getUserRoles`
 
@@ -1127,11 +1127,11 @@ Lock the colony's token. Can only be called by a network-managed extension.
 
 |Name|Type|Description|
 |---|---|---|
-|uint256|uint256|
+|timesLocked|uint256|The amount of times the token was locked
 
 ### `makeArbitraryTransaction`
 
-Execute arbitrary transaction on behalf of the Colony DEPRECATED
+Execute arbitrary transaction on behalf of the Colony
 
 
 **Parameters**
@@ -1258,7 +1258,7 @@ Move a given amount: `_amount` of `_token` funds from funding pot with id `_from
 |_permissionDomainId|uint256|The domainId in which I have the permission to take this action
 |_childSkillIndex|uint256|The child index in _permissionDomainId where I will be taking this action
 |_domainId|uint256|The domain where I am taking this action, pointed to by _permissionDomainId and _childSkillIndex
-|_fromChildSkillIndex|uint256|In the array of child skills for the skill associated with the domain pointed to by _permissionDomainId + _childSkillIndex,         the index of the skill associated with the domain that contains _fromPot
+|_fromChildSkillIndex|uint256|In the array of child skills for the skill associated with the domain pointed to by _permissionDomainId + _childSkillIndex, the index of the skill associated with the domain that contains _fromPot
 |_toChildSkillIndex|uint256|The same, but for the _toPot which the funds are being moved to
 |_fromPot|uint256|Funding pot id providing the funds
 |_toPot|uint256|Funding pot id receiving the funds
@@ -1918,7 +1918,7 @@ Updates the expenditure owner. Can only be called by expenditure owner.
 
 ### `transferExpenditureViaArbitration`
 
-DEPRECATED Updates the expenditure owner. Can only be called by Arbitration role.
+Updates the expenditure owner. Can only be called by Arbitration role.
 
 *Note: This is now deprecated and will be removed in a future version*
 
diff --git a/docs/_Interface_IColonyNetwork.md b/docs/_Interface_IColonyNetwork.md
index e0faf05078..77ed27ec1d 100644
--- a/docs/_Interface_IColonyNetwork.md
+++ b/docs/_Interface_IColonyNetwork.md
@@ -468,7 +468,7 @@ Called to get the address _delegate is allowed to mine for
 
 |Name|Type|Description|
 |---|---|---|
-|address|address|
+|delegator|address|The address they are allowed to mine on behalf of
 
 ### `getMiningResolver`
 
@@ -532,7 +532,7 @@ Get a token's status in the payout whitelist
 
 |Name|Type|Description|
 |---|---|---|
-|status|bool|
+|status|bool|Will be `true` if token is whitelisted
 
 ### `getProfileDBAddress`
 
@@ -613,7 +613,7 @@ Called to get the total per-cycle reputation mining reward.
 
 |Name|Type|Description|
 |---|---|---|
-|uint256|uint256|
+|amount|uint256|The CLNY awarded per mining cycle to the miners
 
 ### `getReputationMiningSkillId`
 
@@ -920,7 +920,7 @@ Called to set the total per-cycle reputation reward, which will be split between
 
 |Name|Type|Description|
 |---|---|---|
-|_amount|uint256|
+|_amount|uint256|The CLNY awarded per mining cycle to the miners
 
 
 ### `setReputationRootHash`
diff --git a/docs/_Interface_IMetaColony.md b/docs/_Interface_IMetaColony.md
index ea959bc8da..1051877b46 100644
--- a/docs/_Interface_IMetaColony.md
+++ b/docs/_Interface_IMetaColony.md
@@ -109,4 +109,4 @@ Called to set the total per-cycle reputation reward, which will be split between
 
 |Name|Type|Description|
 |---|---|---|
-|_amount|uint256|
\ No newline at end of file
+|_amount|uint256|The CLNY awarded per mining cycle to the miners
\ No newline at end of file
diff --git a/docs/_Interface_ITokenLocking.md b/docs/_Interface_ITokenLocking.md
index d7e299aa85..be4ab26e3b 100644
--- a/docs/_Interface_ITokenLocking.md
+++ b/docs/_Interface_ITokenLocking.md
@@ -38,7 +38,7 @@ Deobligate the user some amount of tokens, releasing the stake. Can only be call
 
 ### `deposit`
 
-DEPRECATED Deposit `_amount` of deposited tokens. Can only be called if user tokens are not locked. Before calling this function user has to allow that their tokens can be transferred by token locking contract.
+Deposit `_amount` of deposited tokens. Can only be called if user tokens are not locked. Before calling this function user has to allow that their tokens can be transferred by token locking contract.
 
 
 **Parameters**
@@ -297,7 +297,7 @@ Increments the lock counter to `_lockId` for the `_user` if user's lock count is
 
 ### `withdraw`
 
-DEPRECATED Withdraw `_amount` of deposited tokens. Can only be called if user tokens are not locked.
+Withdraw `_amount` of deposited tokens. Can only be called if user tokens are not locked.
 
 
 **Parameters**
diff --git a/scripts/versioningCheck.sh b/scripts/versioningCheck.sh
index 7037756cb3..692531f9a8 100644
--- a/scripts/versioningCheck.sh
+++ b/scripts/versioningCheck.sh
@@ -1,7 +1,9 @@
 LATEST_RELEASE=`curl --silent "https://api.github.com/repos/joinColony/colonyNetwork/releases/latest" | grep -Po '"tag_name": "\K.*?(?=")'`
 
+NO_COMMENT_REGEX="^[ \t]*[^\/ \t][^\/ \t].*$"
+
 # Are there changes in the colony contract?
-N=`git diff --cached --name-only $LATEST_RELEASE contracts/colony/ | wc -l`
+N=`git diff --cached --name-only -G"$NO_COMMENT_REGEX" $LATEST_RELEASE contracts/colony/ | wc -l`
 
 version_from_commit() {
 	COMMIT=$1;
@@ -34,7 +36,7 @@ if [ $N -ne 0 ]; then
 fi
 
 # Now the same for the extensions
-for file in $(git diff --cached --name-only $LATEST_RELEASE | grep -E 'contracts/extensions/')
+for file in $(git diff --cached --name-only -G"$NO_COMMENT_REGEX" $LATEST_RELEASE | grep -E 'contracts/extensions/')
 do
 	if [ $file = "contracts/extensions/ColonyExtension.sol" ]; then
 		continue
@@ -44,14 +46,19 @@ do
 		continue
 	fi
 
-	oldVersion="$(version_from_commit_extensions $LATEST_RELEASE $file)"
+	if git show $LATEST_RELEASE:$file > /dev/null 2>&1 ; then
 
-	# What version does the staged version have?
-	newVersion="$(version_from_commit_extensions '' $file)"
+		oldVersion="$(version_from_commit_extensions $LATEST_RELEASE $file)"
 
-	if [ $newVersion -eq $oldVersion ]; then
-		echo "Version not bumped for $file when it should be"
-		STATUS=1;
+		# What version does the staged version have?
+		newVersion="$(version_from_commit_extensions '' $file)"
+
+		if [ $newVersion -eq $oldVersion ]; then
+			echo "Version not bumped for $file when it should be"
+			STATUS=1;
+		fi
+	else
+		echo "$file is new, and doesn't exist in latest release; skipping."
 	fi
 
 done