Merge pull request #1088 from JoinColony/maint/add-more-extension-docs

Add even more extension docs

Author: kronosapiens

contracts/extensions/EvaluatedExpenditure.sol

@@ -33,12 +33,14 @@ contract EvaluatedExpenditure is ColonyExtension, BasicMetaTransaction {
   mapping(address => uint256) metatransactionNonces;
 
   /// @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("EvaluatedExpenditure");
   }
 
   /// @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 2;
   }
 
@@ -54,6 +56,7 @@ contract EvaluatedExpenditure 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;
   }
@@ -63,6 +66,9 @@ contract EvaluatedExpenditure is ColonyExtension, BasicMetaTransaction {
     selfdestruct(address(uint160(address(colony))));
   }
 
+  /// @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];
   }

contracts/extensions/FundingQueue.sol

@@ -73,6 +73,10 @@ contract FundingQueue is ColonyExtension, PatriciaTreeProofs, BasicMetaTransacti
   // Technically a circular singly-linked list
   mapping (uint256 => uint256) queue; // proposalId => nextProposalId
   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];
   }
@@ -84,12 +88,14 @@ contract FundingQueue is ColonyExtension, PatriciaTreeProofs, BasicMetaTransacti
   // Public functions
 
   /// @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("FundingQueue");
   }
 
   /// @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 3;
   }
 
@@ -110,6 +116,7 @@ contract FundingQueue is ColonyExtension, PatriciaTreeProofs, BasicMetaTransacti
   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 {
     deprecated = _deprecated;
   }
@@ -119,6 +126,16 @@ contract FundingQueue is ColonyExtension, PatriciaTreeProofs, BasicMetaTransacti
     selfdestruct(address(uint160(address(colony))));
   }
 
+  // Public
+
+  /// @notice Create a new funding proposal
+  /// @param _domainId The domain the extension has the funding permission
+  /// @param _fromChildSkillIndex The index of the fromPot's domain in _domainId.children[]
+  /// @param _toChildSkillIndex The index of the toPot's domain in _domainId.children[]
+  /// @param _fromPot Funding pot id providing the funds
+  /// @param _toPot Funding pot id receiving the funds
+  /// @param _totalRequested The total amount being requested
+  /// @param _token The token being transferred
   function createProposal(
     uint256 _domainId,
     uint256 _fromChildSkillIndex,
@@ -170,6 +187,9 @@ contract FundingQueue is ColonyExtension, PatriciaTreeProofs, BasicMetaTransacti
     emit ProposalCreated(proposalCount, _fromPot, _toPot, _token, _totalRequested);
   }
 
+  /// @notice Cancel a funding proposal and remove from linked list
+  /// @param _id The proposal Id
+  /// @param _prevId The id of the preceding proposal in the linked list
   function cancelProposal(uint256 _id, uint256 _prevId) public {
     Proposal storage proposal = proposals[_id];
 
@@ -189,6 +209,12 @@ contract FundingQueue is ColonyExtension, PatriciaTreeProofs, BasicMetaTransacti
     emit ProposalCancelled(_id);
   }
 
+  /// @notice Stake a funding proposal
+  /// @param _id The proposal Id
+  /// @param _key A reputation hash tree key, of the total reputation in _domainId
+  /// @param _value Reputation value indicating the total reputation in _domainId
+  /// @param _branchMask The branchmask of the proof
+  /// @param _siblings The siblings of the proof
   function stakeProposal(
     uint256 _id,
     bytes memory _key,
@@ -212,6 +238,15 @@ contract FundingQueue is ColonyExtension, PatriciaTreeProofs, BasicMetaTransacti
     emit ProposalStaked(_id, proposal.domainTotalRep);
   }
 
+  /// @notice Back a funding proposal and advance it along the list
+  /// @param _id The proposal Id
+  /// @param _backing The amount of backing to give the proposal (up to user's reputation)
+  /// @param _currPrevId The current previous proposal in the list
+  /// @param _newPrevId The new previous proposal after we re-arrange
+  /// @param _key A reputation hash tree key, of the caller's reputation in _domainId
+  /// @param _value Reputation value indicating the caller's reputation in _domainId
+  /// @param _branchMask The branchmask of the proof
+  /// @param _siblings The siblings of the proof
   function backProposal(
     uint256 _id,
     uint256 _backing,
@@ -269,6 +304,8 @@ contract FundingQueue is ColonyExtension, PatriciaTreeProofs, BasicMetaTransacti
     emit ProposalBacked(_id, _newPrevId, msgSender(), _backing, prevBacking);
   }
 
+  /// @notice Transfer the marginal funds
+  /// @param _id The proposal Id
   function pingProposal(uint256 _id) public {
     Proposal storage proposal = proposals[_id];
 
@@ -324,6 +361,8 @@ contract FundingQueue is ColonyExtension, PatriciaTreeProofs, BasicMetaTransacti
     emit ProposalPinged(_id, actualFundingToTransfer);
   }
 
+  /// @notice Reclaim the stake after the proposal is funded
+  /// @param _id The proposal Id
   function reclaimStake(uint256 _id) public {
     Proposal storage proposal = proposals[_id];
 
@@ -338,19 +377,31 @@ contract FundingQueue is ColonyExtension, PatriciaTreeProofs, BasicMetaTransacti
 
   // Public view functions
 
-  function getProposalCount() public view returns (uint256) {
+  /// @notice Get the total number of proposals
+  /// @return count The count
+  function getProposalCount() public view returns (uint256 count) {
     return proposalCount;
   }
 
+  /// @notice Get the proposal struct for a given proposal
+  /// @param _id The proposal Id
+  /// @return proposal The proposal struct
   function getProposal(uint256 _id) public view returns (Proposal memory proposal) {
     return proposals[_id];
   }
 
-  function getSupport(uint256 _id, address _supporter) public view returns (uint256) {
+  /// @notice Gets the reputation support from a user to a proposal
+  /// @param _id The proposal Id
+  /// @param _supporter The supporter
+  /// @return support The support amount
+  function getSupport(uint256 _id, address _supporter) public view returns (uint256 support) {
     return supporters[_id][_supporter];
   }
 
-  function getNextProposalId(uint256 _id) public view returns (uint256) {
+  /// @notice Gets the id of the next proposal in the list
+  /// @param _id The proposal Id
+  /// @return nextId The next proposal Id in the list
+  function getNextProposalId(uint256 _id) public view returns (uint256 nextId) {
     return queue[_id];
   }
 

contracts/extensions/StakedExpenditure.sol

@@ -58,12 +58,14 @@ contract StakedExpenditure is ColonyExtensionMeta, PatriciaTreeProofs {
   // Overrides
 
   /// @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("StakedExpenditure");
   }
 
   /// @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 1;
   }
 
@@ -79,6 +81,7 @@ contract StakedExpenditure is ColonyExtensionMeta, PatriciaTreeProofs {
   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;
   }
@@ -253,13 +256,14 @@ contract StakedExpenditure is ColonyExtensionMeta, PatriciaTreeProofs {
   // View
 
   /// @notice Get the stake fraction
-  /// @return stakeFraction The stake fraction
-  function getStakeFraction() public view returns (uint256) {
+  /// @return _stakeFraction The stake fraction
+  function getStakeFraction() public view returns (uint256 _stakeFraction) {
     return stakeFraction;
   }
 
   /// @notice Get the stake for an expenditure
-  /// @param stake The stake, a struct holding the staker's address and the stake amount
+  /// @param _expenditureId The id of the expenditure to get the stake for
+  /// @return stake The stake, a struct holding the staker's address and the stake amount
   function getStake(uint256 _expenditureId) public view returns (Stake memory stake) {
     return stakes[_expenditureId];
   }

contracts/extensions/StreamingPayments.sol

@@ -79,12 +79,14 @@ contract StreamingPayments is ColonyExtensionMeta {
   // 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("StreamingPayments");
   }
 
   /// @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 1;
   }
 
@@ -100,6 +102,7 @@ contract StreamingPayments is ColonyExtensionMeta {
   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;
   }
@@ -341,6 +344,7 @@ contract StreamingPayments is ColonyExtensionMeta {
 
   /// @notice Cancel the streaming payment, specifically by setting endTime to block.timestamp, and waive claim
   /// to specified tokens already earned. Only callable by the recipient.
+  /// @param _id The id of the streaming payment
   /// @param _tokens The tokens to waive any claims to.
   function cancelAndWaive(
     uint256 _id,
@@ -366,19 +370,32 @@ contract StreamingPayments is ColonyExtensionMeta {
 
   // View
 
+  /// @notice Get the streaming payment struct by Id
+  /// @param _id The id of the streaming payment
+  /// @return streamingPayment The streaming payment struct
   function getStreamingPayment(uint256 _id) public view returns (StreamingPayment memory streamingPayment) {
     streamingPayment = streamingPayments[_id];
   }
 
+  /// @notice Get the payment token struct by Id and token
+  /// @param _id The id of the streaming payment
+  /// @param _token The address of the token
+  /// @return paymentToken The payment token struct
   function getPaymentToken(uint256 _id, address _token) public view returns (PaymentToken memory paymentToken) {
     paymentToken = paymentTokens[_id][_token];
   }
 
-  function getNumStreamingPayments() public view returns (uint256) {
+  /// @notice Get the total number of streaming payments
+  /// @return numPayments The total number of streaming payments
+  function getNumStreamingPayments() public view returns (uint256 numPayments) {
     return numStreamingPayments;
   }
 
-  function getAmountEntitledFromStart(uint256 _id, address _token) public view returns (uint256) {
+  /// @notice Get the amount entitled to claim from the start of the stream
+  /// @param _id The id of the streaming payment
+  /// @param _token The address of the token
+  /// @return amount The amount entitled
+  function getAmountEntitledFromStart(uint256 _id, address _token) public view returns (uint256 amount) {
     StreamingPayment storage streamingPayment = streamingPayments[_id];
     PaymentToken storage paymentToken = paymentTokens[_id][_token];
     if (streamingPayment.startTime >= block.timestamp){

contracts/extensions/TokenSupplier.sol

@@ -43,6 +43,9 @@ contract TokenSupplier is ColonyExtension, BasicMetaTransaction {
 
   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];
   }
@@ -61,12 +64,14 @@ contract TokenSupplier 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("TokenSupplier");
   }
 
   /// @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 3;
   }
 
@@ -82,7 +87,8 @@ contract TokenSupplier is ColonyExtension, BasicMetaTransaction {
   /// @notice Called when upgrading the extension (currently a no-op)
   function finishUpgrade() public override auth {}
 
-  /// @notice Called when deprecating (or undeprecating) the extension (currently a no-op)
+  /// @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 {}
 
   /// @notice Called when uninstalling the extension
@@ -160,19 +166,27 @@ contract TokenSupplier is ColonyExtension, BasicMetaTransaction {
     }
   }
 
-  function getTokenSupplyCeiling() public view returns (uint256) {
+  /// @notice Get the token supply ceiling
+  /// @return supplyCeiling The token supply ceiling
+  function getTokenSupplyCeiling() public view returns (uint256 supplyCeiling) {
     return tokenSupplyCeiling;
   }
 
-  function getTokenIssuanceRate() public view returns (uint256) {
+  /// @notice Get the token issuance rate
+  /// @return issuanceRate The token issuance rate
+  function getTokenIssuanceRate() public view returns (uint256 issuanceRate) {
     return tokenIssuanceRate;
   }
 
-  function getLastPinged() public view returns (uint256) {
+  /// @notice Get the time of the last token minting event
+  /// @return lastPinged The timestamp of the last ping
+  function getLastPinged() public view returns (uint256 lastPinged) {
     return lastIssue;
   }
 
-  function getLastRateUpdate() public view returns (uint256) {
+  /// @notice Get the time of the last change in issuance rate
+  /// @return lastUpdate The timestamp of the last update
+  function getLastRateUpdate() public view returns (uint256 lastUpdate) {
     return lastRateUpdate;
   }
 

docs/.templates/evaluatedexpenditure.md

@@ -0,0 +1,7 @@
+# Evaluated Expenditure (`EvaluatedExpenditure`)
+
+Evaluated Expenditures is a simple extension which allows the owner of an expenditure
+to update the payout modifiers after the expenditure is locked, effectively enabling
+the "evaluation" functionality we initially described as a part of the Tasks flow.
+Without this extension, payout modifiers can only be set by the Arbitration permission
+once the expenditure is locked, making it tedious to implement evaluation workflows.

docs/.templates/fundingqueue.md

@@ -0,0 +1,9 @@
+# Funding Queue (`FundingQueue`)
+
+Funding Queues are a core mechanic described in the Colony whitepaper,
+allowing for teams to allocate resources in a distributed manner. Members of
+a colony can make and back funding proposals, requesting that some number of tokens be
+transferred between domains. The more reputation backing a proposal, the more
+quickly the proposal is fulfilled, up to a maximum of half of the source domain's
+assets per week. By creating and bacing funding proposals throughout the colony,
+a steady flow of resources from the root through the domains can be achieved.

docs/.templates/icolony.md

@@ -1 +1,10 @@
 # Colony (`IColony`)
+
+The main body of functionality of a colony. If extensions can be thought of
+as "applications", providing specific functionality, then this contract can
+be thought of as the "operating system", providing "system calls" for managing
+a colony's underlying resources, such as managing roles & permissions,
+creating new domains and expenditures, and moving resources throughout a
+colony. Extensions express their functionality by calling these functions
+on the colony on which they are installed, and users with the proper
+permissions can call these functions directly.

docs/.templates/icolonynetwork.md

@@ -1 +1,7 @@
 # Colony Network (`IColonyNetwork`)
+
+The functions for managing the Colony Network as a whole. Includes functions
+for creating and upgrading colonies, managing the reputation mining process,
+managing the skills used in colonies, and managing colony ENS names.
+These functions are not publically callable, but rather callable by
+the Meta Colony, a special colony which controls the network.