Add extensions contracts to docgen

.circleci/config.yml

@@ -118,6 +118,9 @@ jobs:
       - run:
           name: "Linting Solidity"
           command: npm run solhint
+      - run:
+          name: "Building Docs"
+          command: npm run build:docs
       - run:
           name: "Check git hooks run"
           command: npm run check:gitchanges

docs/README.md → .github/README.md

@@ -1,5 +1,5 @@
 <div align="center">
-  <img src="https://rawcdn.githack.com/JoinColony/colonyNetwork/c8d22052/docs/img/colonyNetwork_color.svg" width="600" />
+  <img src="https://raw.githubusercontent.com/JoinColony/brand/v1.0.0/logo_network.svg" width="600" />
 </div>
 <div align="center">
   <a href="https://circleci.com/gh/JoinColony/colonyNetwork">

.husky/pre-commit

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+npm run check:versioning && npm run eslint-staged && npm run solhint-staged && npm run build:docs && git add docs

contracts/colony/IColony.sol

@@ -493,6 +493,7 @@ interface IColony is ColonyDataTypes, IRecovery, IBasicMetaTransaction {
   function setExpenditurePayoutModifiers(uint256 _id, uint256[] memory _slots, int256[] memory _payoutModifiers) external;
 
   /// @notice Set many values of an expenditure simultaneously. Can only be called by expenditure owner.
+  /// @param _id Expenditure identifier
   /// @param _recipientSlots Array of slots to set recipients
   /// @param _recipients Addresses of the recipients
   /// @param _skillIdSlots Array of slots to set skills
@@ -501,8 +502,8 @@ interface IColony is ColonyDataTypes, IRecovery, IBasicMetaTransaction {
   /// @param _claimDelays Durations of time (in seconds) to delay
   /// @param _payoutModifierSlots Array of slots to set payout modifiers
   /// @param _payoutModifiers Values (between +/- WAD) to modify the payout & reputation bonus
-  /// @param _payoutSlots 2-dimensional array of slots to set payouts
   /// @param _payoutTokens Addresses of the tokens, `0x0` value indicates Ether
+  /// @param _payoutSlots 2-dimensional array of slots to set payouts
   /// @param _payoutValues 2-dimensional array of the payout amounts
   function setExpenditureValues(
     uint256 _id,

contracts/colonyNetwork/ColonyNetworkExtensions.sol

@@ -149,6 +149,8 @@ contract ColonyNetworkExtensions is ColonyNetworkStorage {
     token.setOwner(msgSender());
 
     emit TokenDeployed(address(token));
+
+    return address(token);
   }
 
   function deployTokenAuthority(address _token, address _colony, address[] memory allowedToTransfer) public
@@ -158,6 +160,8 @@ contract ColonyNetworkExtensions is ColonyNetworkStorage {
     TokenAuthority tokenAuthority = new TokenAuthority(_token, _colony, allowedToTransfer);
 
     emit TokenAuthorityDeployed(address(tokenAuthority));
+
+    return address(tokenAuthority);
   }
 
 

contracts/extensions/CoinMachine.sol

@@ -67,8 +67,11 @@ contract CoinMachine is ColonyExtension, BasicMetaTransaction {
   mapping(address => uint256) soldUser; // Tokens sold to a particular user
 
   mapping(address => uint256) metatransactionNonces;
-  function getMetatransactionNonce(address userAddress) override public view returns (uint256 nonce){
-    return metatransactionNonces[userAddress];
+  /// @notice Gets the next nonce for a meta-transaction
+  /// @param _userAddress The user's address
+  /// @return _nonce The nonce
+  function getMetatransactionNonce(address _userAddress) override public view returns (uint256 _nonce){
+    return metatransactionNonces[_userAddress];
   }
 
   function incrementMetatransactionNonce(address user) override internal {
@@ -85,12 +88,14 @@ contract CoinMachine is ColonyExtension, BasicMetaTransaction {
   // Public
 
   /// @notice Returns the identifier of the extension
-  function identifier() public override pure returns (bytes32) {
+  /// @return _identifier The extension's identifier
+  function identifier() public override pure returns (bytes32 _identifier) {
     return keccak256("CoinMachine");
   }
 
   /// @notice Returns the version of the extension
-  function version() public override pure returns (uint256) {
+  /// @return _version The extension's version number
+  function version() public override pure returns (uint256 _version) {
     return 6;
   }
 
@@ -111,6 +116,7 @@ contract CoinMachine is ColonyExtension, BasicMetaTransaction {
   }
 
   /// @notice Called when deprecating (or undeprecating) the extension
+  /// @param _deprecated Indicates whether the extension should be deprecated or undeprecated
   function deprecate(bool _deprecated) public override auth {
     deprecated = _deprecated;
 
@@ -139,6 +145,7 @@ contract CoinMachine is ColonyExtension, BasicMetaTransaction {
   /// @param _windowSize Characteristic number of periods that should be used for the moving average. In the long-term, 86% of the weighting will be in this window size. The higher the number, the slower the price will be to adjust
   /// @param _targetPerPeriod The number of tokens to aim to sell per period
   /// @param _maxPerPeriod The maximum number of tokens that can be sold per period
+  /// @param _userLimitFraction The fraction of the total sale that a single user can buy (in WAD)
   /// @param _startingPrice The sale price to start at, expressed in units of _purchaseToken per token being sold, as a WAD
   /// @param _whitelist Optionally an address of a whitelist contract to use can be provided. Pass 0x0 if no whitelist being used
   function initialise(
@@ -287,62 +294,74 @@ contract CoinMachine is ColonyExtension, BasicMetaTransaction {
   }
 
   /// @notice Get the address of the token being used to make purchases
-  function getPurchaseToken() public view returns (address) {
+  /// @return _token The token's address
+  function getPurchaseToken() public view returns (address _token) {
     return purchaseToken;
   }
 
   /// @notice Get the address of the token being sold
-  function getToken() public view returns (address) {
+  /// @return _token The token's address
+  function getToken() public view returns (address _token) {
     return token;
   }
 
   /// @notice Get the period that the price was last updated for or a purchase was made
-  function getActivePeriod() public view returns (uint256) {
+  /// @return _period The active period
+  function getActivePeriod() public view returns (uint256 _period) {
     return activePeriod;
   }
 
   /// @notice Get the number of tokens sold in the period that the price was last updated for or a purchase was made
-  function getActiveSold() public view returns (uint256) {
+  /// @return _sold Amount of tokens sold
+  function getActiveSold() public view returns (uint256 _sold) {
     return activeSold;
   }
 
   /// @notice Get the number of tokens received in the period that the price was last updated for or a purchase was made
-  function getActiveIntake() public view returns (uint256) {
+  /// @return _intake Amount of tokens received
+  function getActiveIntake() public view returns (uint256 _intake) {
     return activeIntake;
   }
 
   /// @notice Get the EMA of the number of tokens received each period
-  function getEMAIntake() public view returns (uint256) {
+  /// @return _amount Amount of tokens received
+  function getEMAIntake() public view returns (uint256 _amount) {
     return emaIntake;
   }
 
   /// @notice Get the remaining balance of tokens
-  function getTokenBalance() public view returns (uint256) {
+  /// @return _balance Remaining token balance
+  function getTokenBalance() public view returns (uint256 _balance) {
     return ERC20(token).balanceOf(address(this));
   }
 
   /// @notice Get the length of the sale period
-  function getPeriodLength() public view returns (uint256) {
+  /// @return _length Length of the sale period
+  function getPeriodLength() public view returns (uint256 _length) {
     return periodLength;
   }
 
   /// @notice Get the size of the averaging window
-  function getWindowSize() public view returns (uint256) {
+  /// @return _size Size of the averaging window
+  function getWindowSize() public view returns (uint256 _size) {
     return windowSize;
   }
 
   /// @notice Get the target number of tokens to sell per period
-  function getTargetPerPeriod() public view returns (uint256) {
+  /// @return _target Target number of tokens
+  function getTargetPerPeriod() public view returns (uint256 _target) {
     return targetPerPeriod;
   }
 
   /// @notice Get the maximum number of tokens to sell per period
-  function getMaxPerPeriod() public view returns (uint256) {
+  /// @return _max Maximum number of tokens
+  function getMaxPerPeriod() public view returns (uint256 _max) {
     return maxPerPeriod;
   }
 
   /// @notice Get the current price per token
-  function getCurrentPrice() public view returns (uint256) {
+  /// @return _price Current price
+  function getCurrentPrice() public view returns (uint256 _price) {
     uint256 currentPeriod = getCurrentPeriod();
 
     if (activePeriod >= currentPeriod || !evolvePrice) {
@@ -366,12 +385,15 @@ contract CoinMachine is ColonyExtension, BasicMetaTransaction {
   }
 
   /// @notice Get the number of remaining tokens for sale this period
-  function getSellableTokens() public view returns (uint256) {
+  /// @return _remaining Tokens remaining
+  function getSellableTokens() public view returns (uint256 _remaining) {
     return sub(maxPerPeriod, ((activePeriod >= getCurrentPeriod()) ? activeSold : 0));
   }
 
   /// @notice Get the maximum amount of tokens a user can purchase in total
-  function getUserLimit(address _user) public view returns (uint256) {
+  /// @param _user The user's address
+  /// @return _max Maximum amount of tokens
+  function getUserLimit(address _user) public view returns (uint256 _max) {
     return
       (userLimitFraction == WAD || whitelist == address(0x0)) ?
       UINT256_MAX :
@@ -380,20 +402,24 @@ contract CoinMachine is ColonyExtension, BasicMetaTransaction {
   }
 
   /// @notice Get the maximum amount of tokens a user can purchase in a period
-  function getMaxPurchase(address _user) public view returns (uint256) {
+  /// @param _user The user's address
+  /// @return _max Maximum amount of tokens
+  function getMaxPurchase(address _user) public view returns (uint256 _max) {
     uint256 tokenBalance = getTokenBalance();
     uint256 sellableTokens = getSellableTokens();
     uint256 userLimit = getUserLimit(_user);
     return min(userLimit, min(tokenBalance, sellableTokens));
   }
 
   /// @notice Get the address of the whitelist (if exists)
-  function getWhitelist() public view returns (address) {
+  /// @return _whitelist Address of Whitelist contract
+  function getWhitelist() public view returns (address _whitelist) {
     return whitelist;
   }
 
   /// @notice Get the evolvePrice boolean
-  function getEvolvePrice() public view returns (bool) {
+  /// @return _evolve The evolvePrice boolean
+  function getEvolvePrice() public view returns (bool _evolve) {
     return evolvePrice;
   }
 

contracts/extensions/OneTxPayment.sol

@@ -31,6 +31,10 @@ contract OneTxPayment is ColonyExtension, BasicMetaTransaction {
   ColonyDataTypes.ColonyRole constant FUNDING = ColonyDataTypes.ColonyRole.Funding;
 
   mapping(address => uint256) metatransactionNonces;
+
+  /// @notice Gets the next nonce for a meta-transaction
+  /// @param userAddress The user's address
+  /// @return nonce The nonce
   function getMetatransactionNonce(address userAddress) override public view returns (uint256 nonce){
     return metatransactionNonces[userAddress];
   }
@@ -40,13 +44,15 @@ contract OneTxPayment is ColonyExtension, BasicMetaTransaction {
   }
 
   /// @notice Returns the identifier of the extension
-  function identifier() public override pure returns (bytes32) {
+  /// @return _identifier The extension's identifier
+  function identifier() public override pure returns (bytes32 _identifier) {
     return keccak256("OneTxPayment");
   }
 
   /// @notice Returns the version of the extension
-  function version() public override pure returns (uint256) {
-    return 3;
+  /// @return _version The extension's version number
+  function version() public override pure returns (uint256 _version) {
+    return 4;
   }
 
   /// @notice Configures the extension
@@ -61,6 +67,7 @@ contract OneTxPayment is ColonyExtension, BasicMetaTransaction {
   function finishUpgrade() public override auth {} // solhint-disable-line no-empty-blocks
 
   /// @notice Called when deprecating (or undeprecating) the extension
+  /// @param _deprecated Indicates whether the extension should be deprecated or undeprecated
   function deprecate(bool _deprecated) public override auth {} // solhint-disable-line no-empty-blocks
 
   /// @notice Called when uninstalling the extension
@@ -83,8 +90,8 @@ contract OneTxPayment is ColonyExtension, BasicMetaTransaction {
 
   /// @notice Return the permissions required for each function
   /// @param _sig The function signature
-  /// @return The byte32 of permissions required
-  function getCapabilityRoles(bytes4 _sig) public view override returns (bytes32) {
+  /// @return _roles The byte32 of permissions required
+  function getCapabilityRoles(bytes4 _sig) public view override returns (bytes32 _roles) {
     if (_sig == MAKE_PAYMENT_SIG || _sig == MAKE_PAYMENT_DOMAIN_SIG) {
       return REQUIRED_ROLES;
     } else {

contracts/extensions/Whitelist.sol

@@ -40,6 +40,9 @@ contract Whitelist is ColonyExtension, BasicMetaTransaction {
   mapping (address => bool) signatures;
   mapping(address => uint256) metatransactionNonces;
 
+  /// @notice Gets the next nonce for a meta-transaction
+  /// @param userAddress The user's address
+  /// @return nonce The nonce
   function getMetatransactionNonce(address userAddress) override public view returns (uint256 nonce){
     return metatransactionNonces[userAddress];
   }
@@ -59,13 +62,15 @@ contract Whitelist is ColonyExtension, BasicMetaTransaction {
   // Public
 
   /// @notice Returns the identifier of the extension
-  function identifier() public override pure returns (bytes32) {
+  /// @return _identifier The extension's identifier
+  function identifier() public override pure returns (bytes32 _identifier) {
     return keccak256("Whitelist");
   }
 
   /// @notice Returns the version of the extension
-  function version() public override pure returns (uint256) {
-    return 2;
+  /// @return _version The extension's version number
+  function version() public override pure returns (uint256 _version) {
+    return 3;
   }
 
   /// @notice Configures the extension
@@ -80,6 +85,7 @@ contract Whitelist is ColonyExtension, BasicMetaTransaction {
   function finishUpgrade() public override auth {}
 
   /// @notice Called when deprecating (or undeprecating) the extension
+  /// @param _deprecated Indicates whether the extension should be deprecated or undeprecated
   function deprecate(bool _deprecated) public override auth {
     deprecated = _deprecated;
   }
@@ -134,7 +140,8 @@ contract Whitelist is ColonyExtension, BasicMetaTransaction {
 
   /// @notice Get the user's overall whitelist status
   /// @param _user The address of the user
-  function isApproved(address _user) public initialised view returns (bool) {
+  /// @return _approved Is `true` when the user is approved
+  function isApproved(address _user) public initialised view returns (bool _approved) {
     return (
       !deprecated &&
       (!useApprovals || approvals[_user]) &&
@@ -143,24 +150,28 @@ contract Whitelist is ColonyExtension, BasicMetaTransaction {
   }
 
   /// @notice Get the useApprovals boolean
-  function getUseApprovals() public view returns (bool) {
+  /// @return _useApprovals Whether `useApprovals` is `true`
+  function getUseApprovals() public view returns (bool _useApprovals) {
     return useApprovals;
   }
 
   /// @notice Get the agreementHash
-  function getAgreementHash() public view returns (string memory) {
+  /// @return _hash The agreement hash
+  function getAgreementHash() public view returns (string memory _hash) {
     return agreementHash;
   }
 
   /// @notice Get the user's approval status
   /// @param _user The address of the user
-  function getApproval(address _user) public view returns (bool) {
+  /// @return _status The user's approval status
+  function getApproval(address _user) public view returns (bool _status) {
     return approvals[_user];
   }
 
   /// @notice Get the user's signature status
   /// @param _user The address of the user
-  function getSignature(address _user) public view returns (bool) {
+  /// @return _status The user's signature status
+  function getSignature(address _user) public view returns (bool _status) {
     return signatures[_user];
   }
 }