solidity docs for mock methods (#14)

* add docs.
* remove stale method.

Author: raulk

contracts/v0.8/MarketAPI.sol

@@ -3,20 +3,30 @@ pragma solidity >=0.4.25 <=0.8.15;
 
 import "./types/MarketTypes.sol";
 
+/// @title This contract is a proxy to the singleton Storage Market actor (address: f05). Calling one of its methods will result in a cross-actor call being performed. However, in this mock library, no actual call is performed.
+/// @author Zondax AG
+/// @dev Methods prefixed with mock_ will not be available in the real library. These methods are merely used to set mock state. Note that this interface will likely break in the future as we align it
+//       with that of the real library!
 contract MarketAPI {
     mapping(string => uint256) balances;
     mapping(uint64 => MarketTypes.MockDeal) deals;
 
     constructor() {
-        generate_deal_mocks();
+        mock_generate_deals();
     }
 
+    /// Deposits the received value into the balance held in escrow.
+    /// @dev Because this is a mock method, no real balance is being deducted from the caller, nor incremented in the Storage Market actor (f05).
     function add_balance(
         MarketTypes.AddBalanceParams memory params
     ) public payable {
         balances[params.provider_or_client] += msg.value;
     }
 
+    /// Attempt to withdraw the specified amount from the balance held in escrow.
+    /// If less than the specified amount is available, yields the entire available balance.
+    /// @dev This method should be called by an approved address, but the mock does not check that the caller is an approved party.
+    /// @dev Because this is a mock method, no real balance is deposited in the designated address, nor decremented from the Storage Market actor (f05).
     function withdraw_balance(
         MarketTypes.WithdrawBalanceParams memory params
     ) public returns (MarketTypes.WithdrawBalanceReturn memory) {
@@ -31,6 +41,7 @@ contract MarketAPI {
         return MarketTypes.WithdrawBalanceReturn(tmp);
     }
 
+    /// Returns the escrow balance and locked amount for an address.
     function get_balance(
         string memory addr
     ) public view returns (MarketTypes.GetBalanceReturn memory) {
@@ -39,7 +50,11 @@ contract MarketAPI {
         return MarketTypes.GetBalanceReturn(actualBalance, 0);
     }
 
-    // FIXME set data values correctly
+    /// Returns the data commitment and size of a deal proposal.
+    /// This will be available after the deal is published (whether or not is is activated)
+    /// and up until some undefined period after it is terminated.
+    /// FIXME set data values correctly, currently returning fixed data, feel free to adjust
+    /// in your local mock.
     function get_deal_data_commitment(
         MarketTypes.GetDealDataCommitmentParams memory params
     ) public view returns (MarketTypes.GetDealDataCommitmentReturn memory) {
@@ -52,6 +67,7 @@ contract MarketAPI {
             );
     }
 
+    /// Returns the client of a deal proposal.
     function get_deal_client(
         MarketTypes.GetDealClientParams memory params
     ) public view returns (MarketTypes.GetDealClientReturn memory) {
@@ -60,6 +76,7 @@ contract MarketAPI {
         return MarketTypes.GetDealClientReturn(deals[params.id].client);
     }
 
+    /// Returns the provider of a deal proposal.
     function get_deal_provider(
         MarketTypes.GetDealProviderParams memory params
     ) public view returns (MarketTypes.GetDealProviderReturn memory) {
@@ -68,6 +85,7 @@ contract MarketAPI {
         return MarketTypes.GetDealProviderReturn(deals[params.id].provider);
     }
 
+    /// Returns the label of a deal proposal.
     function get_deal_label(
         MarketTypes.GetDealLabelParams memory params
     ) public view returns (MarketTypes.GetDealLabelReturn memory) {
@@ -76,6 +94,7 @@ contract MarketAPI {
         return MarketTypes.GetDealLabelReturn(deals[params.id].label);
     }
 
+    /// Returns the start epoch and duration (in epochs) of a deal proposal.
     function get_deal_term(
         MarketTypes.GetDealTermParams memory params
     ) public view returns (MarketTypes.GetDealTermReturn memory) {
@@ -88,6 +107,8 @@ contract MarketAPI {
             );
     }
 
+    /// Returns the per-epoch price of a deal proposal.
+    /// TODO renamed to get_deal_total_price in builtin-actors.
     function get_deal_epoch_price(
         MarketTypes.GetDealEpochPriceParams memory params
     ) public view returns (MarketTypes.GetDealEpochPriceReturn memory) {
@@ -99,6 +120,7 @@ contract MarketAPI {
             );
     }
 
+    /// Returns the client collateral requirement for a deal proposal.
     function get_deal_client_collateral(
         MarketTypes.GetDealClientCollateralParams memory params
     ) public view returns (MarketTypes.GetDealClientCollateralReturn memory) {
@@ -110,6 +132,7 @@ contract MarketAPI {
             );
     }
 
+    /// Returns the provider collateral requirement for a deal proposal.
     function get_deal_provider_collateral(
         MarketTypes.GetDealProviderCollateralParams memory params
     ) public view returns (MarketTypes.GetDealProviderCollateralReturn memory) {
@@ -121,6 +144,9 @@ contract MarketAPI {
             );
     }
 
+    /// Returns the verified flag for a deal proposal.
+    /// Note that the source of truth for verified allocations and claims is
+    /// the verified registry actor.
     function get_deal_verified(
         MarketTypes.GetDealVerifiedParams memory params
     ) public view returns (MarketTypes.GetDealVerifiedReturn memory) {
@@ -129,6 +155,11 @@ contract MarketAPI {
         return MarketTypes.GetDealVerifiedReturn(deals[params.id].verified);
     }
 
+    /// Fetches activation state for a deal.
+    /// This will be available from when the proposal is published until an undefined period after
+    /// the deal finishes (either normally or by termination).
+    /// Returns USR_NOT_FOUND if the deal doesn't exist (yet), or EX_DEAL_EXPIRED if the deal
+    /// has been removed from state.
     function get_deal_activation(
         MarketTypes.GetDealActivationParams memory params
     ) public view returns (MarketTypes.GetDealActivationReturn memory) {
@@ -141,6 +172,8 @@ contract MarketAPI {
             );
     }
 
+    /// Publish a new set of storage deals (not yet included in a sector).
+    /// TODO renamed to publish_storage_deals, taking a vector.
     function publish_deal(bytes memory raw_auth_params, address callee) public {
         // calls standard filecoin receiver on message authentication api method number
         (bool success, ) = callee.call(
@@ -154,7 +187,9 @@ contract MarketAPI {
         require(success, "client contract failed to authorize deal publish");
     }
 
-    function generate_deal_mocks() internal {
+    /// Adds mock deal data to the internal state of this mock.
+    /// @dev Feel free to adjust the data here to make it align with deals in your network.
+    function mock_generate_deals() internal {
         MarketTypes.MockDeal memory deal_67;
         deal_67.id = 67;
         deal_67
@@ -174,7 +209,7 @@ contract MarketAPI {
 
         deals[deal_67.id] = deal_67;
 
-        // As EVM smart contract has a limited capacity for size, we cannot set all deals directly here.
+        // As EVM smart contract has a limited capacity for size (24KiB), we cannot set all deals directly here.
         // Please, take them from docs.
 
         // Add or replace more deals here.

contracts/v0.8/MinerAPI.sol

@@ -3,10 +3,10 @@ pragma solidity >=0.4.25 <=0.8.15;
 
 import "./types/MinerTypes.sol";
 
-/// @title Filecoin miner actor API for Solidity.
+/// @title This contract is a proxy to a built-in Miner actor. Calling one of its methods will result in a cross-actor call being performed. However, in this mock library, no actual call is performed.
 /// @author Zondax AG
-/// @notice It is mock with specific scenarios based on the parameters used to call its methods. It is meant to serve as the first entry point, and be replaced seamlessly in the future by the real API implementation tath actually calls the filecoin actor.
-/// @dev Most of function calls are currently implemented using some kind of struct for parameters and returns.
+/// @dev Methods prefixed with mock_ will not be available in the real library. These methods are merely used to set mock state. Note that this interface will likely break in the future as we align it
+//       with that of the real library!
 contract MinerAPI {
     string owner;
     bool isBeneficiarySet = false;
@@ -23,11 +23,15 @@ contract MinerAPI {
         sectorSizesBytes[CommonTypes.SectorSize._64GiB] = 2 * (32 << 30);
     }
 
+    /// (Mock method) Sets the owner of a Miner, which will be returned via get_owner().
     function mock_set_owner(string memory addr) public {
         require(bytes(owner).length == 0);
         owner = addr;
     }
 
+    /// Returns the owner address of a Miner.
+    /// - Income and returned collateral are paid to this address
+    /// - This address is also allowed to change the worker address for the miner
     function get_owner()
         public
         view
@@ -38,16 +42,24 @@ contract MinerAPI {
         return MinerTypes.GetOwnerReturn(owner);
     }
 
+    /// Proposes or confirms a change of owner address.
+    /// If invoked by the current owner, proposes a new owner address for confirmation. If the proposed address is the
+    /// current owner address, revokes any existing proposal.
+    /// If invoked by the previously proposed address, with the same proposal, changes the current owner address to be
+    /// that proposed address.
     function change_owner_address(string memory addr) public {
         owner = addr;
     }
 
+    /// Returns whether the provided address is "controlling".
+    /// The "controlling" addresses are the Owner, the Worker, and all Control Addresses.
     function is_controlling_address(
         MinerTypes.IsControllingAddressParam memory params
     ) public pure returns (MinerTypes.IsControllingAddressReturn memory) {
         return MinerTypes.IsControllingAddressReturn(false);
     }
 
+    /// Returns the miner's sector size.
     function get_sector_size()
         public
         view
@@ -59,6 +71,9 @@ contract MinerAPI {
             );
     }
 
+    /// Returns the available balance of this miner.
+    /// This is calculated as actor balance - (vesting funds + pre-commit deposit + initial pledge requirement + fee debt)
+    /// Can go negative if the miner is in IP debt.
     function get_available_balance()
         public
         pure
@@ -67,6 +82,7 @@ contract MinerAPI {
         return MinerTypes.GetAvailableBalanceReturn(10000000000000000000000);
     }
 
+    /// Returns the funds vesting in this miner as a list of (vesting_epoch, vesting_amount) tuples.
     function get_vesting_funds()
         public
         pure
@@ -82,6 +98,10 @@ contract MinerAPI {
         return MinerTypes.GetVestingFundsReturn(vesting_funds);
     }
 
+    /// Proposes or confirms a change of beneficiary address.
+    /// A proposal must be submitted by the owner, and takes effect after approval of both the proposed beneficiary and current beneficiary,
+    /// if applicable, any current beneficiary that has time and quota remaining.
+    /// See FIP-0029, https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0029.md
     function change_beneficiary(
         MinerTypes.ChangeBeneficiaryParams memory params
     ) public {
@@ -100,6 +120,9 @@ contract MinerAPI {
         }
     }
 
+    /// Retrieves the currently active and proposed beneficiary information.
+    /// This method is for use by other actors (such as those acting as beneficiaries),
+    /// and to abstract the state representation for clients.
     function get_beneficiary()
         public
         view
@@ -110,6 +133,4 @@ contract MinerAPI {
         CommonTypes.PendingBeneficiaryChange memory proposed;
         return MinerTypes.GetBeneficiaryReturn(activeBeneficiary, proposed);
     }
-
-    function get_sector_size_from_enum() internal returns (uint64) {}
 }